You are here:
Hostname Aliases for B2C Commerce
A hostname alias defines alternative names for an existing website URL. You must set up and register the DNS and domain names to use hostnames aliases in a B2C store. A hostname alias can map a human-readable hostname onto a more technical hostname. A hostname alias can also redirect one external, human-readable domain to another, such as www.mystore.com to www.yourstore.com.
Merchants create hostname aliases for the following reasons:
- Add a site-path mapping to allow multiple sites to share one domain.
For example, site 1, locale A is
www.my-shop.com/us, site 2, locale A iswww.my-shop.com/uk, and site 2, locale B iswww.my-shop.com/de. - Retain the site traffic from old sites if the sites are not operational by
redirecting to the new site names. For example, redirect
www.myothershopdomain.comto the new sitewww.myshop.com. - Accommodate misspelling of site names. For example, amerzon instead of amazon or
www.myshop.comandwww.myshops.com. - Associate an alias with a locale so that a specific hostname automatically triggers
the correct language and region settings. For example,
www.myshop.detriggers thede_DE locale. - Associate an alias with a landing page so that a hostname redirects directly to the
specific category page. For example,
shoes.myshop.comredirects to the Shoes category page - Associate an alias with device-specific pages so that customers on web-ready devices, such as mobile phones, can access the site with mobile layout.
Production Instance Hostname
The Production instance hostname is similar to
your.instance.hostname.example.com, with an IP address such as
100.100.100.1. You can use this hostname to access Business Manager
and to connect to UX Studio, WebDav, and other development tools. While you can use the
production instance hostname 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 isn’t secure.
Accessing the Storefront Homepage with Your Hostname
If you want to use your own hostname to directly access the storefront homepage and link to an SSL certificate, you must do the following:
- Purchase a domain, and configure your DNS (Domain Name Service) for that domain to define a hostname.
- 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.netand 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. - Replace the generic production instance hostname with a public-facing,
brand-friendly domain. Create a hostname alias to ensure shoppers access the
storefront using a branded URL (for example,
www.mydomain.com) that promotes brand recognition and customer trust. - Add the hostname to your hostname alias file. In Business Manager, click App
Launcher, and select .
Note If you set any HTTP/HTTPS hostname in your hostname alias file, the URL for the storefront includes that hostname. If you don’t add HTTP/HTTPS in the URL, the preview URL uses the first configured hostname. - If your host is listed in Business Manager: , 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.
- If your host is configured as an alias in Business Manager: , and the site uses only one locale, you can create links to the home page. These search-friendly links 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 can 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 is 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 or domains that B2C Commerce supports. The hostname alias file 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 information on mappings, see URL Redirects.
You can create a set of rules that controls how B2C Commerce processes different URLs. These rules use the JSON (Java Script Object Notation) format (see Json.Org).
Include the proper https-host in the alias file. 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" } }
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.
For additional information on how B2C Commerce constructs URLs, see URL Rules URL Syntax.
File Format
The following code shows the basic file format:
{"__version": "1",
"settings": {
"http-host": "httphostname",
"https-host": "httpshostname",
"job-hostnames":
{
"default":"www.my-default-host.com",
"de":"www.my-de-host.com",
"en":"www.my-en-host.com"
},
"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 value is changed to any other number, all entries are ignored. |
| settings* | Optional. When you set this property, you can specify the following:
|
| 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’s 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 your own DNS hostname address
(your.instance.hostname.example.com). The hostname address can also
include the realm or name of a partner who is implementing the site.
{
"__version": "1",
"www.mybrand.com" : [{"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 hostnames 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":"/" }]Use the alias file to direct
shoppers to a specific pipeline or landing page based on the hostname entered in the
URL. This functionality 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 don’t match
mobile.
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 it includes an error. Debug the File 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 to use a JSON alias file.
It's not possible to set up a URL redirect or mappings for the following paths
because B2C Commerce reserves the keywords dw,
_dw, and s.
http://hostname/dw
http://hostname/_dw
http://hostname/sMapping Rule Syntax
Each mapping rule is defined by a set of attributes. Consider this example.
{
"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 through your aliases file configuration and handle hostname redirects for these requests: When perform hostname redirects for these requests, 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 Dynamic Mappings. |
| description | Optional. Describe the parameter. For example, using |
| 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 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 Note The if-site-path and site-path
parameters are only valid in the corresponding section, where
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. When
using if-site-path statement in a hostname rule, site-path and
http(s)-host in the settings sections must be empty or defined for a
different hostname.” |
| 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. |
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 |
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=aValueIs redirected to the following:
www.your-other-hostname.com/?reqParam=aValue&cfgParam=aOtherValueExample 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.ukand you want to change it towww.my-site.com/UK. - Site 2 in the past used
www.my-site.comand you want to change it towww.my-site.com/US. - Site 3 in the past used
www.my-site.deand you want to change it towww.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 isen_UK) should now redirect towww.my-site.com/UK. - The existing host name
www.my-site.com(whose locale isen_US, the default locale) should now redirect towww.my-site.com/US. - The existing host name
www.my-site.de(whose locale isde_DE) should now redirect towww.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.eushould work by itself without a site path. B2C Commerce should direct the URL to site 1, and the default locale should been. - The URL segment
www.my-site.eu/DEshould direct the URL to site 1, and the locale should bede. - The URL segment
www.my-site.eu/FRshould direct the URL to site 1, and the locale should befr. - The URL segment
www.my-site.eu/USshould direct the URL to site 2, and the locale should been.
For the second host name (www.my-site.com), you want to specify the following:
- The host name
www.my-site.comshould work by itself without a site path. B2C Commerce should direct the URL to site 2, and the default locale should been. - The URL segment
www.my-site.com/FRshould direct the URL to site 2, and the locale should befr. - The URL segment
www.my-site.com/UKshould direct the URL to site 1, and the locale should been. - The URL segment
www.my-site.com/DEshould direct the URL to site 1, and the locale should bede.
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 |
Example 12: Preferred Hostnames for URL Generation Without Request Context
To avoid custom code, the alias file now supports a mapping to define hostnames within the job context. The mapping can be locale-specific, and follow a language fallback from country to language to default locale.
These hostnames will be used for URL generation when:
- hostname is undefined within an URLAction.
- the HTTP/HTTPS hostname isn’t defined for this site.
- no request context is available.
Mappings are validated to contain only hostnames pointing to the site where the configuration is added.
"settings" :
{
"job-hostnames" :
{
"default":"www.my-default-host.com",
"de":"www.my-de-host.com",
"en":"www.my-en-host.com"
}
},
"www.my-default-host.com":[{}],
"www.my-de-host.com":[{}],
"www.my-en-host.com":[{}],The returned hostname for locales (following the language fallback) are as follow:
- default = www.my-default-host.com
- de = www.my-de-host.com
- de_XX = www.my-de-host.com
- en = www.my-en-host.com
- en_XX = www.my-en-host.com
- yy = www.my-default-host.com
- yy_XX = www.my-default-host.com
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:
- Determine the IP address of your test system. Enter
nslookup your.instance.hostname.example.cominto a console. - Add a hostname mapping to your locale machine's hosts file, typically located in
/etc/hosts: 123.45.678.91 my-test-hostname.com. - Use this or all hostnames that are (locally) pointing to the instance to verify and test your hosts 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.
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.
Step 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
settingsproperty) to handle the URL, and then continue to step 5. - No - continue to step 2.
Step 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.
Step 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 totrue, use the first site in the sites list to handle the URL, and continue to step 5. - No - continue to step 4.
Step 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.
Step 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-Startpipeline 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.
Step 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, andparamsproperties. Ignore all other property values (for example, ignore theif-agent-containsproperty). Use thename,locale,pipeline, andparamsproperty values to determine how to handle the request. If the entered URL specifies only the hostName and sitePath, check to see if thepipelineandparamsproperties are set; if so, execute the configuredpipelineusing the configuredparams(if any); if thepipelineandparamproperties are not set, execute theDefault-Startpipeline, 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.
Step 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-containsmust be included as the first mapping in a rule or it's never reached.
Step 8: Is the if-agent-contains condition true?
- Yes - then process the mapping rule containing the
if-agent-containsrule. - No - process the rule or condition after the rule associated with the previous
if-agent-containsrule.
Step 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
pipelineproperty value, forward the request to the pipeline using thepipeline,locale,andparamsproperties. - If the rule specifies a
hostproperty value, redirect to the specified host. - If the rule provides a
path, construct a redirect URL by appending the value from the providedpathparameter to the value of thehostproperty. If no value is configured for thehostproperty, ignore thepathproperty. - If the rule doesn't provide any parameters, forward the request to the
Default-Startpipeline.
- If the rule specifies a
-
No - the entered URL contains at least a partial path and looks like this:
http://www.sitegenesis.com/electronics- If the rule provides a
hostproperty value, replace the URL host with thehostvalue and use the rest of the path in the entered URL to construct a 301 redirect. - If the rule provides a
pathbut nohostproperty value, thepathvalue is ignored.
- If the rule provides a
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:
- If a mapping rule specifies an
if-site-pathproperty but doesn't specify alocaleproperty, the value of the if-site-path property is used as the site path for the default locale. - For all other locales, the first
if-site-pathrule with the specifiedlocaledetermines the site path. (An empty site path is possible with a locale-only rule, if it is the first rule for this locale.) - Activated site locales that are not configured in mappings use the mapping for default locale. If the default locale is defined, then the site path isn’t empty.
