--- schema_version: "1" id: f75a0a6d3c55489f8b64b304e824f98a73515ab0b9bb5213767b97fa40280de2 title: Maintenance Pages collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/b2c-commerce/guides/admin/b2c-maintenance-pages.md canonical_url: https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-maintenance-pages.html source_site: developer.salesforce.com content_type: documentation content_hash: c6b046753a017a5e55a14f7d8eacdddfa0b2339544df2c530c37c2a019979f5b products: - Composable Storefront - Salesforce APIs --- # Maintenance Pages If your site is undergoing maintenance, 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. **note:** This task requires permissions for the **Administration** > **Custom Maintenance Pages** module and the **Merchant Tools** > **SEO** > **Aliases** module on the Production instance. ## Create Your Maintenance Page 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. **note:** 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: ```html ``` `www.mystore.com` is the site FQDN. CSS syntax ```html ``` `www.mystore.com` is the site FQDN. - Relative links aren't 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 aren't allowed. So `/www.mystore.com/index.html` can't refer to `/shop.mystore.com/logo.gif`. ## Create an aliases.json File 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: ```json { "hostname": "foldername", "hostname": "foldername" } ``` Example 1: aliases.json File This example shows a simple aliases.json file. ```json { "luxbrand.eu": "www.luxbrand.eu", "luxbrand-store.at": "www.luxbrand.eu", "luxbrand-store.de": "www.luxbrand.eu", "luxbrand-store.eu": "www.luxbrand.eu", "shoebrand.com": "www.shoebrand.com", "kidsshoebrand.com": "www.shoebrand.com", "nonoprofit.net": "www.nonoprofit.net", "drinkbrand.com": "www.drinkbrand.com", "drinkbrand.event.com": "www.drinkbrand.com", "intlbrand.at": "www.intlbrand.at", "intlbrand.ch": "www.intlbrand.ch", "intlbrand.com": "www.intlbrand.com", "intlbrand.de": "www.intlbrand.de", "intlbrand.eu": "www.intlbrand.eu", "intlbrand.fr": "www.intlbrand.fr", "intlbrand.nl": "www.intlbrand.nl", "intlbrand-online.be": "www.intlbrand-online.be", "intlbrand.si": "www.intlbrand.si" } ``` ## Maintenance Page Scenarios 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. Instead, add all the language text to appear on a single HTML page. Optionally, create a simple language selector dropdown that shows the selected language text to the user. See an example of how to specify separate maintenance pages for different locales in the `intlbrand` site in the aliases.json code example. 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 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. 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 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 ```txt +-- aliases.json +-- www.mystore.com +-- index.html +-- files (folder) +-- logo.png +-- mystore.css ``` See this structure by downloading the sample file available from the page. **note:** Don't include operating system files, such as the .DS_store on the mac in your .zip file. The uploaded .zip file can have any name. **important:** The zip file name determines which files are affected by publishing the maintenance page. Any sites that aren't included in subsequent uploads are deleted when you publish the pages. For example, assume you upload and publish `Realm1SiteABC.zip`, containing maintenance pages for site A, B, and C. If you then upload `Realm1SiteABC.zip` again, this time containing maintenance pages for site A and B; the maintenance page for site C is deleted. However, assume you upload and publish `Realm1SiteABC.zip`, containing maintenance pages for site A, B, and C and then upload and publish `Realm2SiteDEF.zip`, containing maintenance pages for site D, E, and F. In this case, sites A-F have maintenance pages and none are deleted, because the .zip files they were uploaded from have different names. 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. ## Preview 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. ## Publish Publish maintenance pages on Production instances only. 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. **note:** You must publish the maintenance page at least 2 hours before you intend to use it for your site maintenance window. 1. Select **Administration** > **Site Development** > **Maintenance Pages**. 2. On the Custom Maintenance Pages page, click **Publish**. ## Troubleshoot 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/](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: ```json { "www.sitegenesis.com": "www.sitegenesis.com" } ``` 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. ## Maintenance Pages for Separate Realms or Sites 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`.