Maintenance Pages

If your site is undergoing maintenance, you can upload custom maintenance pages that are shown to the customer. We support one custom maintenance page per FQDN (Fully Qualified Domain Name).

An FQDN is a complete domain name. For example, www.mystore.com is an FQDN. www is the host; mystore is the second-level domain; and .com is the top-level domain.

You can download a .zip file with an example of the required maintenance page structure and best practices on any instance.

1. Select Administration > Site Development > Custom Maintenance Pages.

2. On the Custom Maintenance Pages page, click Download.

3. Select site > Merchant Tools > Aliases. Identify the domain names that you want to create maintenance pages for.

   Any site you want to create a maintenance page for must have its domain name configured in the hostname aliases file. The default file for an instance shows a sample of text, but the entries are commented out.

4. Create a .zip file and maintenance page that follows the following constraints:

   • The top level of the .zip file must contain one or more folders with your site name, as defined on the Aliases page.

   • If you have sites with more than one public domain or want the maintenance page used for more than one site, create an aliases.json file. Put the file at the top of the .zip file.

   • Use a single HTML page to render the entire maintenance page.

   • The HTML page must be named index.html and placed at the top of the site folder.

   • Make the HTML code as simple as possible. If you must use JavaScript, keep it to a minimum and don't use ISML includes or other web-based languages at all.

   • Images and other page assets must be located in the top directory or a single subdirectory only.

   • All HTML references to images, CSS, and JavaScript must include the FQDN.

     Image syntax:

     www.mystore.com is the site FQDN.

     CSS syntax

     www.mystore.com is the site FQDN.

   • Relative links are not allowed. Child files and directories of the FQDN are allowed, but any link must refer to the absolute path within the .zip file. So given www.mystore.com/index.html and www.mystore.com/images/logo.gif, the link to the gif from the HTML must be /www.mystore.com/images/logo.gif. A relative path of images/logo.gif isn't supported.

   • Use lowercase characters for links only.

   • Links between domains are not allowed. So /www.mystore.com/index.html can't refer to /shop.mystore.com/logo.gif.

The aliases.json file uses the name of the site defined in the Manage Sites page for a key and the name of the folder to upload that contains the maintenance page for the site. This file is optional and used when you want to define the relationship between one or more sites and a maintenance page.

The syntax of the file is:

Example 1: aliases.json File

This example shows a simple aliases.json file.

If necessary, adjust your index.html or aliases.json file for different scenarios.

Maintenance Pages and Multiple Locales

If you have multiple sites for different languages, such as mysite.de and mysite.fr, then each FQDN can have a separate maintenance page uploaded, regardless of what B2C Commerce site the FQDN actually points to. For example, mystore.de and mystore.fr might both point to Sites-mystore-Site.

However, if you have only one FQDN then you can't upload multiple maintenance pages for each language the site supports. You can, however, add all the language text to appear on a single HTML page. You can also create a simple language selector dropdown that shows the selected language text to the user.

You can see an example of how to specify separate maintenance pages for different locales in the intlbrand site in the aliases.json code example.

You can see an example of how to specify the same maintenance page for multiple locales in the luxbrand site in the aliases.json code example.

Sharing maintenance pages between Sites

You can specify a single maintenance page to be shared by multiple sites, by adding multiple site keys with the same folder value in the aliases.json file.

You can see an example of how to specify the same maintenance page for multiple domain names in the kidsshoebrand and shoebrand sites in the aliases.json code example.

Sites Without Configured Custom Pages

Any public name for a site must be configured to use a custom page. Otherwise, the B2C Commerce default maintenance page appears. For example, assume you have a site name of Sites-mystore-Site with public names mystore.com and shop.mystore.com. If mystore.com is configured to use a custom page , but shop.mystore.com isn't. Any shopper hitting the sites when the maintenance page is enabled, sees the following:

• mystore.com: The custom page.
• shop.mystore.com: The B2C Commerce default maintenance page.

The default maintenance page isn't the page available for sample download, but an internal page that can't be edited.

You can see an example of how to specify the same maintenance page for multiple domain names in the drankbrand site in the aliases.json code example. In the example, both the main site and an event branded site name should use the same maintenance page.

Maintenance pages per channel Type

If you want to provide a separate experience for the maintenance page, based on the device or channel type used to access the page, create an index.html that uses responsive design and takes channel type into account.

Upload the page as one .zip file that includes the following:

• index.html at the top level of the .zip file
• a single folder, containing CSS files or images
• (optional) an aliases.json file

Sample structure

You can see this structure by downloading the sample file available from the page.

The uploaded .zip file can have any name.

To upload your file:

1. Select Administration > Site Development > Maintenance Pages.
2. On the Custom Maintenance Pages page, in the Upload section, click Browse.
3. Navigate to the .zip file you want to upload.
4. Click Upload.

After you upload successfully, the zip file is automatically extracted and the content is on the web server. If you receive errors when uploading, see the Troubleshooting section in this topic.

You can preview maintenance pages on Sandbox or Production instances after you have successfully uploaded your template.

1. Select Administration > Site Development > Maintenance Pages.

2. On the Custom Maintenance Pages page, click Preview.

   The page appears as it appears during site maintenance.

You can only publish maintenance pages on Production instances. It isn't possible to undo publishing a maintenance page. Salesforce recommends keeping an older version of the page available to publish in case you decide to roll back changes.

1. Select Administration > Site Development > Maintenance Pages.
2. On the Custom Maintenance Pages page, click Publish.

Both warnings and errors can be significant enough to prevent the maintenance page from appearing successfully. Be sure to resolve all warnings or errors. In general, it might be a good idea to run your JSON through a debugger, such as http://www.jsonlint.com/.

Usually, the warnings or errors that you receive contain information that you need to resolve the problem.

Cannot resolve URLs

Make sure that the left-hand key values in your alias.json file are present in your hostname and not commented out. The default hostname file for a new instance contains sample information which is entirely commented out.

Bad Alias

If the domain in the hostname alias file and the folder name are identical, you don't have to include a value and key. Including such an entry causes an error. For example, don't create an alias file that looks like the following:

Instead, remove the line if it's in a file with multiple lines or don't include the aliases.json file if it's the only line in the file.

Depending on your site architecture and the teams maintaining it, you might need to have multiple administrators uploading maintenance pages for one or more sites.

Maintenance pages are available to the organization as a whole. Any administrator can upload maintenance pages for any site. However, B2C Commerce informs you if you are uploading a duplicate of an existing page. This is true even if you have a different alias assigned to the site in your aliases.json file.

Maintenance Pages and PODs

Maintenance pages are not POD-specific. They are maintained for all PODs. For example, if the maintenance page was first installed here: http://maintenance.pod29.demandware.net/www.mysite.com/index.html, but the realm moved PODs, the maintenance page is maintained on the next POD. For example, this would show the same maintenance page as well: http://maintenance.pod17.demandware.net/www.mysite.com/index.html.