--- schema_version: "1" id: 9cd0d1d917123f9e0c1d1fbc0e6704b6d34e7bee02543aef418c68d80fa9e70a title: Hostname Aliases for B2C Commerce collection: admin version: current locale: en-us portal_url: https://docs.salesforce.com/admin/current/en-us/cc/264-0-0/b2c_hostname_aliases.md canonical_url: https://help.salesforce.com/s/articleView?id=cc.b2c_hostname_aliases.htm&release=264.0.0&type=5 source_site: help.salesforce.com content_type: documentation content_hash: 6aaada201e43041c85868066187cbab81e89876ca31646da89d4949897e09ef5 description: 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. products: - Commerce - B2C Commerce release: "264" --- # 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 is `www.my-shop.com/uk`, and site 2, locale B is `www.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.com` to the new site `www.myshop.com`. - Accommodate misspelling of site names. For example, amerzon instead of amazon or `www.myshop.com` and `www.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.de` triggers the `de_DE locale.` - Associate an alias with a landing page so that a hostname redirects directly to the specific category page. For example, `shoes.myshop.com` redirects 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.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. - 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 click App Launcher ![App Launcher](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-cc-b2c_merchandiser_administrator-264-0-0-production-enus/ea76f372-6cfa-42a6-8e7c-05c6df7abed8/cc/b2c_merchandiser_administrator/images/appLauncher.png), and then select **Merchant Tools** | **Site** | **SEO** | **Aliases**. ![Note](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-cc-b2c_merchandiser_administrator-264-0-0-production-enus/ea76f372-6cfa-42a6-8e7c-05c6df7abed8/images/icon_note.png) 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: **site** | **SEO & Discoverability** | **Aliases**, and only one locale is used for the site, you can [create links to the home page](https://help.salesforce.com/s/articleView?id=cc.b2c_creating_home_page_links.htm&release=264.0.0&type=5 "If your host is listed as an alias, 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. In this case, you can use a hostname-only URL instead of generating links to the homepage via a B2C Commerce pipeline. If you have a multi-locale site, ignore the rest of this topic.") 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: **site** | **SEO & Discoverability** | **Aliases**, 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](https://help.salesforce.com/s/articleView?id=cc.b2c_url_redirects.htm&release=264.0.0&type=5 "During the initial transition between an existing site and a new B2C Commerce store, consider creating 301 redirects from the old site to the new site. Over time, create redirects from one page or URL to another."). 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](http://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](https://help.salesforce.com/s/articleView?id=cc.b2c_configuring_hostname_alias.htm&release=264.0.0&type=5 "A hostname alias is required to create short, meaningful URLs for external search engines to index. Assign at least one hostname alias that is the current hostname on which the B2C Commerce instance is running."). You can also configure your hostname alias file to [avoid multiple entry points](https://help.salesforce.com/s/articleView?id=cc.b2c_avoiding_duplicate_home_page_urls.htm&release=264.0.0&type=5 "Duplicate content is content that appears on a B2C Commerce site for two (or more) URLs without a redirect. Even though the way search engines determine the search rating of a page changes frequently, most search engines decrease the search rating for such content. To have the best search ratings for your page, avoid duplicate content.") 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](https://help.salesforce.com/s/articleView?id=cc.b2c_url_rules_url_syntax.htm&release=264.0.0&type=5 "Define how your storefront URLs look in B2C Commerce via two types of URL syntax: standard B2C Commerce URL syntax or SEO URL syntax. The syntax you use depends on which Business Manager module you have enabled."). ## 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 } ] } ``` ![Note](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-cc-b2c_merchandiser_administrator-264-0-0-production-enus/ea76f372-6cfa-42a6-8e7c-05c6df7abed8/images/icon_note.png) 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. 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:

  • 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.
  • job-HostNames: mapping to define job hostnames, which are used for URL generation within the job context only if the HTTP or HTTPS hostnames aren’t defined for the same site. The mapping can be locale-specific and follow a language fallback from country to language to default locale.
  • 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 don’t 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
    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’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. ![Warning](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-cc-b2c_merchandiser_administrator-264-0-0-production-enus/ea76f372-6cfa-42a6-8e7c-05c6df7abed8/images/icon_warning.png) 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 it includes an error. [Debug the File](https://help.salesforce.com/s/articleView?id=cc.b2c_hostname_aliases.htm&release=264.0.0&type=5) 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. ![Note](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-cc-b2c_merchandiser_administrator-264-0-0-production-enus/ea76f372-6cfa-42a6-8e7c-05c6df7abed8/images/icon_note.png) Note If you’re migrating from the legacy implementation, changes to the settings don't take effect until you save an alias file for the corresponding site. After removing data from the Settings tab, navigate to SEO, open the alias file, and save it to activate your changes. ![Important](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-cc-b2c_merchandiser_administrator-264-0-0-production-enus/ea76f372-6cfa-42a6-8e7c-05c6df7abed8/images/icon_important.png) Important 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/s ``` ## Mapping 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:

"apply-to-host-only-request-with-params": "true"

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 Creating Home Page Links.

See Dynamic Mappings.
description

Optional. Describe the parameter.

For example, using site-path-trailing-slash: A trailing slash is added (or not) to the redirected 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
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
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. 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 | ![Note](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-cc-b2c_merchandiser_administrator-264-0-0-production-enus/ea76f372-6cfa-42a6-8e7c-05c6df7abed8/images/icon_note.png) 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 | ## 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.com` into 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 `settings` property) 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 to `true`, 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-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. 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`, 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. 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-contains` must 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-contains` rule. - No - process the rule or condition after the rule associated with the previous `if-agent-contains` rule. 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 `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](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-cc-b2c_merchandiser_administrator-264-0-0-production-enus/ea76f372-6cfa-42a6-8e7c-05c6df7abed8/images/icon_note.png) 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: - If a mapping rule specifies an `if-site-path` property but doesn't specify a `locale` property, 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-path` rule with the specified `locale` determines 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.