Configure Hostname Mapping Rules
Learning Objectives
After completing this unit, you’ll be able to:
- Explain the purpose of mapping rules in the alias file.
- Give two reasons for adding mapping rules to a host alias file.
- Explain how B2C Commerce handles duplicate URL mappings.
- List three areas to check in your alias file to ensure it’s valid JSON.
Why Mapping Rules?
Brandon wants to add detailed mapping rules to his alias file. These rules let him map and redirect shoppers to a proper hostname, a specific pipeline, or a landing page. For each event, it can be a mix of mappings and redirects. However, he needs at least one mapping rule in the file for each hostname or domain name for which he has storefront content. Also, his domain name service (DNS) must contain IP addresses that correspond to one of the IP addresses on the production instance.
Here’s a sample mapping rule.
"www.cloudkicks.com" : [{"pipeline": "Home-Show" }],
The www.cloudkicks.com hostname maps to the Home-Show pipeline.
Proper Hostname
Brandon wants to redirect a commonly used hostname to the proper hostname. The site accepts connections for the common name, then redirects or changes the URL to a hostname that’s more appropriate.
Here’s an example.
"cloudkicks.com": [ { "host": "www.cloudkicks.com", "path":"/home" }]
When the shopper types cloudkicks.com as the URL, Salesforce B2C Commerce redirects them to www.cloudkicks.com/home, a proper hostname—because Brandon defined it. However, B2C Commerce would redirect cloudkicks.com/mens to www.cloudkicks.com/mens.
Mapping Rule Syntax
Each mapping rule, defined by a set of attributes, looks something like this.
{
"www.cloudkicks.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.cloudkicks.com",
"path": "index.html",
"pipeline": "Summer-Start",
"locale": "de",
"params": {...},
}
Here’s how B2C Commerce reads each part of this rule.
| Element |
Description |
|---|---|
| "apply-to-host-only-request-with-params":"true"}] |
B2C Commerce processes redirect functionality on host-only requests with parameters per default. When this property is true, the default handling is disabled, requests are forwarded to the defined pipeline, and the parameters populated in memory. |
| "name": "mobile", |
The rule’s name. This is for documentation only and is not interpreted by the system. |
| "If-agent-contains": ["iphone","ipod"], |
The rule is applied to the corresponding user agent. The rule itself can be a pipeline mapping or a redirect. 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-site-path": "DE", |
B2C Commerce recognizes only the name, locale, pipeline, and params properties, and ignores the host, path, and if-agent-contains properties. B2C Commerce also checks this property when it generates storefront URLs. It uses the first mapping rule that matches the current hostname and locale. If the mapping rule that matches specifies a value for the if-site-path property , B2C Commerce adds the site path to the generated URL. |
| "host": "m.cloudkicks.com", |
The name of the host to which the request is redirected. Rules look like this: {"host":"cloudkicks.com", "path":"uk"} or this: {"host":"cloudkicks.com", "pipeline":"Home-Show"} When you specify both, the redirect is unclear because requests with old-hostname + path are redirected to the new-hostname + path, which is used for host-only requests. If you need to choose between these parameters, use the pipeline. |
| "path": "index.html", |
The path the shopper is redirected to via a permanent 301 redirect. B2C Commerce constructs a URL by appending the value of the path property to the value of the host property, for example, cloudkicks.com/index.html. You must configure the host property, for the path property to work. 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": "Summer-Start", |
The hostName that’s used if no host is provided that triggers the pipeline. Use the locale and params syntax to specify a locale and parameters for the file. |
| "locale": "de", |
This sets a locale for each request mapped by this rule, for example, /us/mens. |
| "params": {...}, |
This adds parameters for if the rule is exactly as requested. For example, /us/ (yes) and /us/mens (no). |
See the Infocenter for a complete list.
Debug the Alias File
The B2C Commerce hostname file syntax was inspired by JSON, but isn’t strictly JSON. Some of the syntax isn’t valid JSON, so Brandon might need to change a few things before Vijay tests his file with a debugger. He checks for the following.
- Use colons instead of equal signs when specifying properties. Equal signs are not valid JSON, though they are supported in the hostname syntax.
- Remove all comments in your file. Comments are not valid JSON.
- Remove commas after host entries, because commas are not valid JSON. They are required for the B2C Commerce hostname file, however, so remember to put them back after you debug your file.
Vijay tests that Brandon’s rules are valid JSON in a debugging tool such as the JSONlint validator—and not in Business Manager via trial and error. If the file contains JSON errors, B2C Commerce keeps using the previous good configuration and won’t save an invalid configuration.
Test Time
When it’s time to test, Brandon can’t always get Vijay’s help to configure and register the DNS and domain names for his test environment. Instead, Brandon configures them on his local machine.
Here’s how to test your configuration:
- Determine the IP address of your test system.
- Open a command line.
- Enter nslookup cloudkicks.domain.demandware.net.
- Add a hostname mapping to your locale machine's hosts file, typically located in /etc/hosts.
- Use this or all hostnames that are (locally) pointing to the instance to verify and test your hosts configuration.
It’s best to test on a development instance.
Scenarios
Brandon is ready to review some scenarios.
Scenario 1: Control the Site Path Trailing Slash
Brandon wants to control the site path trailing slash for each site path that has a site-path-trailing-slash setting. This means that he changes the URL from no trailing slash to having a trailing slash.
Here’s how to configure the preferred HTTP/HTTPS site hostname.
"settings" : {
"http-host" : "www.cloudkicks.com",
"https-host" : "www.cloudkicks.com",
"site-path": "en",
"site-path-trailing-slash" : "yes" }
Here’s how to configure the hostname rules for two locales.
"www.cloudkicks.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" } ]
Here’s how B2C Commerce redirects these requests.
| From |
To |
|---|---|
| www.cloudkicks.com/en |
www.cloudkicks.com/en/ |
| www.cloudkicks.com/de/ |
www.cloudkicks.com/de |
Scenario 2: Redirect From an Alternate URL to a Preferred Domain
Brandon redirects the alternate URL cloudkicks.com to the preferred domain. When a shopper enters cloudkicks.com as their URL ( http://cloudkicks.com/*), where * is any path, they are redirected via a 301 redirect to http://www.cloudkicks.com/*.
Here’s the alias file setting.
"cloudkicks.com": [
{
"host": "www.cloudkicks.com",
}
],
What About Duplicates?
When the same content appears on a site from two or more URLs without a redirect, most search engines decrease the search rating for those pages. Brandon avoids duplicate content to get the best search ratings for his pages.
Salesforce B2C Commerce automatically handles most duplicate URL mappings without a configuration change. For alias file mappings (host-only rules and site paths), however, you can add mappings for automatic redirects.
Here’s how to do it.
- Use duplicate resource rules to create URLs via the B2C Commerce Script API.
- Configure rules to define pipelines that have duplicate URL entry points or are contextual equals for a hostname.
- Define the preferred destination.
B2C Commerce generates URLs using the first applicable mapping.
Create URL Rules to Avoid Duplicate Content
Brandon wants to mark a pipeline (StartNode) to be checked for duplicate URLs (defined within the aliases file as host-only or site-path rule). A redirect automatically happens if the URL is not what he defined as the preferred destination configuration.
There are three destination types—host, site-path, and pipeline—with host and site-path requiring a corresponding rule. B2C Commerce uses the first applicable rule to redirect duplicate URLs and to generate URLs.
Here’s an example.
"www.cloudkicks.com" :
[
{ "pipeline" : "StartNode" },
{
"if-site-path" : "eu",
"pipeline" : "StartNode" },
{
"entry-point-pipeline" : [ "Home-Show" ],
"entry-point-destination" : [ "host", "site-path", "pipeline" ]
}
]
With this configuration, B2C Commerce automatically redirects all requests that identify the StartNode pipeline to the host-only destination. The host-only URL invokes the pipeline.