Wizard

Provides a "Step Rail" (loaded via an Application Customized to the top of the page) to show Wizard steps at the top of the page. When the user has complete the Wizard, the rail no longer shows.

Also provides a web part to be used on step pages to navigate between steps.

Configuration

Steps are configured in a JSON file stored in the SiteAssets library of the Hub Site. This file must be called wizardconfig.json.

Example contents of wizardconfig.json file:

{
    "$schema": "https://mercuryblobs.blob.core.windows.net/modern-mercury/wizard.schema.json",
    "steps": [
        {
            "id": 0,
            "title": "Update Your Profile",
            "pageUrl": "/sites/MercuryModernHub/SitePages/Wizard-Step-1.aspx"
        },
        {
            "id": 1,
            "title": "Do Other Stuff",
            "pageUrl": "/sites/MercuryModernHub/SitePages/Wizard-Step-2.aspx"
        },
        {
            "id": 2,
            "title": "Accept Terms and Conditions",
            "pageUrl": "/sites/MercuryModernHub/SitePages/Wizard-Step-3.aspx",
            "isFinal": true
        }
    ]
}

The properites id, title and pageUrl are mandatory. The isFinal button is used to indicate the end of the Wizard, as the Buttons on this page will render a button to Complete the Wizard.

This config is cached in the user's Session Storage. So when updated, close/reopen the tab (don't duplicate, which copies session data over).

You can use the tokens {siteUrl} and {hubSiteUrl} which will be replaced with the current site URL or the Hub Site Url respectively.

An optional property, blockIntranetUntilComplete, can be set to true and added at the top level of the config (after steps), which will force the user to complete the wizard steps before they can proceed to navigate around the intranet. e.g.

{
  "steps": [...],
  "blockIntranetUntilComplete": true
}

Wizard Buttons web part

When the buttons are added to a page, the Previous, Next, and Final buttons can have their text customised.

The buttons must only be used on a page that is defined as a Wizard Step in the config. It will let you know if it doesn't think the current page is configured.

User Wizard Progress / Status

The current user's progress through the Wizard is serialized to JSON and stored in a User Profile Property called ModernMercury-Wizard.

You can reset a user's status back to "clean" using the following PnP PowerShell cmdlets:

Connect-PnPOnline https://mercuryintranet-admin.sharepoint.com
Set-PnPUserProfileProperty -Account 'mercuryadmin@mercuryintranet.onmicrosoft.com' -PropertyName 'ModernMercury-Wizard' -Value ''

The name of this property can be overwritten in the wizard-config.json file by specifying the name of a user profile property with the wizardProgressProperty setting. e.g.

{
  "steps": [...],
  "wizardProgressProperty": "ModernMercuryWizard-ProgressSiteX"
}

This lets you specify different Wizard configurations for different hub sites, and track their progress separately.

Telemetry/Analytics

Currently, telemetry is logged when users click the Back/Next and Complete buttons. There is infrastructure for tracking when the user clicks the steps in the rail, but presently the click isn't being logged (I think it's because the telemetry info is on an A tag, and SharePoint's page hijacking [to enable smooth page to page navigation] is preventing the event bubbling up).