“Under Maintenance” pages for Dynamics 365 portals

It’s common that a single feature update in your portal means modification to multiple components – which can’t be deployed one at a time. Even after proper rehearsal – deploying these changes to a live production environment can be risky business. Any mistakes or delays in your deployment are immediately visible to users.

In these cases it may be decided that the best course of action is to take your portal down and replace it temporarily with a maintenance notice page – informing your users that updates are in progress and the portal will be back up momentarily.

This approach may not be suitable for all situations. Please refer to the Further Consideration section for more details.

An official “maintenance mode” feature is planned for the April 2019 release of Portals. This feature offers the benefits described in this blog post – and also addresses the concerns described below regarding search engine optimization. This blog post offers an interim solution.

 

How it works

We will create a single-page website configuration that displays to all users a simple maintenance notice. You will only need to create it once.

During times of maintenance, you will switch to your maintenance notice configuration, effectively swapping all your regular pages with a “under maintenance” notice. Now you can begin deploying updates to your regular website configuration.

Once you’ve completed your updates, you simply switch back to your regular website configuration. Your portal will be back up and running, and your users won’t be subjected to any half-deployed upgrades.

Setting it up

Website

Create a new Website record.

  • Name – e.g. “Maintenance Notice”
  • Default Language – default system language

Web Templates

Maintenance Notice

Create a new Web Template record.

  • Name – e.g. “Maintenance Notice”
  • Website – same as in previous step
  • Source – HTML content to display when portal is under maintenance

The exact content is your choice. The page should contain content for each language you support.

Empty Header/Footer

Create a new Web Template record.

  • Name – e.g. “Empty”
  • Website – same as in previous step
  • Source – empty

Go back to the Website record you created and set the ‘Header Template’ and ‘Footer Template’ fields to match the empty Web Template record you created.

Page Template

Create a new Page Template record.

  • Name – e.g. “Maintenance Notice”
  • Website – same as in previous step
  • Type – “Web Template”
  • Web Template – same as you created in previous step
  • Use Website Header and Footer – “No” (unchecked)

Publishing State

Create a new Publishing State record.

  • Name – e.g. “Published”
  • Website – same as you created in previous step
  • Is Visible – “Yes” (checked)

Web Page

Create a new Web Page record.

  • Name – e.g. “Maintenance Notice”
  • Website – same as in previous step
  • Parent Page – none
  • Partial URL – “/”
  • Page Template – same as created in previous step
  • Publishing State – same as created in previous step
 

Site Markers

Create a new Site Marker record for each of these:

  • Home
  • Page Not Found

For each Site Setting record, use the following values:

  • Name – name from the list above
  • Website – same as in previous step
  • Page – same as created in previous step

Site Settings

Create a new Site Setting record for each of these settings:

  • Authentication/Registration/AzureADLoginEnabled
  • Authentication/Registration/Enabled
  • Authentication/Registration/ExternalLoginEnabled
  • Authentication/Registration/LocalLoginEnabled

For each Site Setting record, use the following values:

  • Name – name from the list above
  • Website – same as in previous step
  • Value – “false”

Web File (robots.txt)

Technically this step is optional, but is included here for good measure. See the Further Consideration section for more details.

Create a new Web File record.

  • Name – e.g. “robots.txt”
  • Website – same as in previous step
  • Parent Page – same as you created in previous step
  • Partial URL – “robots.txt”
  • Publishing State – same as you created in previous step
  • Content-Disposition – “inline”
Web File

Switch to the “Notes” tab and create a new Note record with a file attachment (your robots.txt file).

Note

The contents of your robots.txt file should look like this:

User-agent: *
Disallow: /

Seeing it in action

Okay – the hard work is done. Now you just need to swap the regular website configuration with the maintenance notice configuration.

Update Portal Binding

In the Portal Admin Center, update the portal binding and select the maintenance notice Website record you created. Then click “Update”.

Restart Portal

Switch to the “Portal Actions” area and click on “Restart”.

The maintenance configuration will be activated and your notice will appear shortly.

Example Maintenance Notice

SWITCHING BACK

Once you’re done deploying your updates for your regular website, simply repeat the Seeing It In Action steps above, but select your regular Website instead of the maintenance notice Website.

Done!

FURTHER CONSIDERATION

This maintenance notice solution is simple and effective, but it does come with some caveats.

Testing

No change is complete without some kind of real-world validation. Unfortunately, you will be unable to test your deployed changes without lifting the maintenance notice – which means also exposing your untested deployment to the world.

One way to mitigate the risks here is to add a similar “maintenance in progress” notice in your website header (and optionally footer) – informing all visitors that maintenance is in progress and some features may be temporarily unavailable.

You can do this by editing the global header (and footer) Web Template records. Add the HTML required to display your notice however you prefer (e.g. a banner alert that appears at the very top of the page). Your HTML will be included in every portal page.

You can find the active header and footer Web Template records by looking at the Website record (example below).

Visibility

Taking down an entire website during periods of maintenance is an increasingly less common practice – and portal users will be quick to complain if they encounter this frequently. There is also an increasing expectation by users for websites to be running 24/7/365.

While a maintenance notice page is an easy solution for your team to implement – it is the last thing your audience wants to see. This approach needs to be carefully weighed against other options that either don’t cause interruptions or allow you to properly scope interruptions (i.e. take down only those sections of your portal that are under maintenance – keeping the rest of your portal up and running).

Do you need a solution for this? Click here to tell Microsoft!

Multiple Languages

You may have noticed that the maintenance notice example above displays content in multiple languages simultaneously. This is the simplest approach. Additional configuration would be required to offer an appropriate user experience that could switch between languages.

Search Engine Optimization

In the unlikely (but still possible) event that a search engine crawler visits your site while your maintenance notice page is active – this could negatively impact how your portal is displayed or ranked in search engine results.

When the maintenance notice configuration described in this post is active, page requests to / or /robots.txt will be responded to with a 200 HTTP status code. Page requests to any other URL will be responded to with a 404 HTTP status code (but users will see your maintenance notice).

What we really want is to respond to all requests with a 503 HTTP status code. This tells search engines that the portal is intentionally and temporarily unavailable – and to check back later.

Currently, there is no way to control the HTTP headers or status code that accompany pages being served in your portal.

You might try to deter search engine crawlers during maintenance periods by adding a robots.txt Web File, or inserting some <meta name=”robots” /> tags into your web pages. But – this may not be ideal and you should speak to an SEO expert about what’s right for you.

Built-in URLs / Endpoints

Portals have several built-in URLs/endpoints, many of which you do not have full control over. The most obvious example of this would be the sign-in page at /SignIn and the related registration pages. You can disable the available sign-in/registration options – but this won’t remove the endpoints themselves – and so users that may have bookmarked the URLs for these will be greeted with either an empty page or a 404 error. They will not see your maintenance notice.

 

Thanks for reading!

If you enjoyed this blog post, be sure to check out the same article on David Jenkin's personal blog XRM Hero, where it was first posted.