10.3 Assisted Setup, Guided Experience & Onboarding Checklists

10.3 Assisted Setup, Guided Experience & Onboarding Checklists

When a customer provisions a new Microsoft Dynamics 365 Business Central environment or installs a third-party AppSource extension, configuring initial settings correctly is critical to achieving fast time-to-value. Rather than forcing administrators to search through complex menus to locate setup tables, Business Central provides the Guided Experience framework in the System Application. This architecture powers the standard Assisted Setup page and dynamic Onboarding Checklists on Role Centers.

1. The Guided Experience Framework Architecture

The Guided Experience module (part of the Microsoft System Application) provides a centralized, extensible registry for all onboarding and configuration workflows across Business Central.

Core Enums in the Guided Experience Framework

1. "Guided Experience Type": Categorizes the type of onboarding experience:
   • "Assisted Setup": A multi-step configuration wizard (typically an AL page with PageType = NavigatePage).
   • "Manual Setup": A standard setup card or worksheet page where users configure settings manually.
   • "Learn": A hyperlink to external conceptual documentation or Microsoft Learn training.
   • "Tour": An interactive In-App teaching tip tour.
   • "Video": An instructional video link.
   • "Application Feature": A direct shortcut to a core functional feature area.
2. "Manual Setup Category": Specifies the functional grouping in the Assisted Setup page (General, Finance, Sales, Purchasing, Inventory, Fixed Assets, HR, System, etc.).

┌───────────────────────────────────────────────────────────────────────┐
│                     System App: Guided Experience                     │
└───────────────────────────────────────────────────────────────────────┘
          │                                              │
          ▼                                              ▼
┌───────────────────────────────┐               ┌───────────────────────┐
│      Assisted Setup Page      │               │ Role Center Checklist │
│ (All Registered System Wizards│               │ (Curated Onboarding   │
│  & Manual Configuration Links)│               │  Tasks for User Role) │
└───────────────────────────────┘               └───────────────────────┘

2. Registering Assisted Setup Wizards in AL

To add an extension's configuration wizard into the standard Assisted Setup page, developers subscribe to the OnRegisterAssistedSetup event published by the Guided Experience codeunit.

Assisted Setup Registration Pattern

codeunit 50135 "Loyalty Guided Exp Subscriber"
{
    [EventSubscriber(ObjectType::Codeunit, Codeunit::"Guided Experience", 'OnRegisterAssistedSetup', '', false, false)]
    local procedure RegisterLoyaltyAssistedSetup()
    var
        GuidedExperience: Codeunit "Guided Experience";
        Language: Codeunit Language;
        CurrentGlobalLanguage: Integer;
    begin
        // Ensure registration strings use application language context
        CurrentGlobalLanguage := GlobalLanguage();

        GuidedExperience.InsertAssistedSetup(
            'Set up Customer Loyalty Management',                           // Title (Mandatory)
            'Loyalty Program Setup',                                       // Short Title
            'Configure loyalty reward tiers, point calculation formulas, and general ledger redemption accounts.', // Description
            10,                                                            // Expected Duration (minutes)
            ObjectType::Page,                                              // Object Type
            Page::"Loyalty Setup Wizard",                                  // Object ID (NavigatePage)
            "Guided Experience Type"::"Assisted Setup",                     // Experience Type
            'https://www.youtube.com/embed/loyalty_setup_tutorial',        // Video URL
            3,                                                             // Video Duration (minutes)
            'https://learn.microsoft.com/dynamics365/business-central/',   // Help / Documentation URL
            "Manual Setup Category"::Sales                                 // Setup Category
        );
    end;
}

GuidedExperience.InsertAssistedSetup Method Parameters Breakdown

3. Developing Multi-Step Setup Wizards (PageType = NavigatePage)

In Business Central, wizards are built using pages with PageType = NavigatePage. A NavigatePage presents a modal dialog with custom banner graphics, step containers shown/hidden based on state, and bottom navigation buttons (Back, Next, Finish).

page 50140 "Loyalty Setup Wizard"
{
    PageType = NavigatePage;
    Caption = 'Customer Loyalty Setup Wizard';
    SourceTable = "Loyalty Setup";
    
    layout
    {
        area(Content)
        {
            // Step 1: Welcome & Introduction
            group(Step1Intro)
            {
                Visible = (CurrentStep = 1);
                group(WelcomeText)
                {
                    Caption = 'Welcome to Loyalty Setup';
                    InstructionalText = 'This wizard guides you through configuring point calculation rates and reward tiers.';
                }
            }
            
            // Step 2: G/L Posting & Calculation Parameters
            group(Step2Settings)
            {
                Visible = (CurrentStep = 2);
                field("Points Per Dollar"; Rec."Points Per Dollar")
                {
                    ApplicationArea = All;
                    ToolTip = 'Specifies points awarded per currency unit spent.';
                }
                field("Redemption Account No."; Rec."Redemption Account No.")
                {
                    ApplicationArea = All;
                    ToolTip = 'Specifies the G/L expense account for point redemptions.';
                }
            }
            
            // Step 3: Confirmation & Completion
            group(Step3Finish)
            {
                Visible = (CurrentStep = 3);
                group(FinishText)
                {
                    Caption = 'Almost Done';
                    InstructionalText = 'Choose Finish to save your settings and activate the loyalty module.';
                }
            }
        }
    }

    actions
    {
        area(Processing)
        {
            action(ActionBack)
            {
                Caption = 'Back';
                Image = PreviousRecord;
                InFooterBar = true;
                Enabled = (CurrentStep > 1);
                
                trigger OnAction()
                begin
                    CurrentStep -= 1;
                end;
            }
            action(ActionNext)
            {
                Caption = 'Next';
                Image = NextRecord;
                InFooterBar = true;
                Visible = (CurrentStep < TotalSteps);
                
                trigger OnAction()
                begin
                    CurrentStep += 1;
                end;
            }
            action(ActionFinish)
            {
                Caption = 'Finish';
                Image = Approve;
                InFooterBar = true;
                Visible = (CurrentStep = TotalSteps);

                trigger OnAction()
                var
                    GuidedExperience: Codeunit "Guided Experience";
                begin
                    // 1. Commit and validate configuration settings
                    Rec.Validate("Setup Completed", true);
                    Rec.Modify(true);

                    // 2. Notify Guided Experience framework of successful completion
                    GuidedExperience.CompleteAssistedSetup(ObjectType::Page, Page::"Loyalty Setup Wizard");

                    // 3. Close the wizard
                    CurrPage.Close();
                end;
            }
        }
    }
    
    trigger OnInit()
    begin
        CurrentStep := 1;
        TotalSteps := 3;
    end;

    var
        CurrentStep: Integer;
        TotalSteps: Integer;
}

Wizard Design Rules for MB-820

1. InFooterBar = true: Navigation actions (Back, Next, Finish) must have the InFooterBar = true property set so they render in the bottom action bar of the NavigatePage.
2. Modal Experience: NavigatePage objects cannot have submenus or standard ribbon action bars; all interactions flow through the footer actions.
3. Step State Control: Step groups are shown conditionally using Visible = (CurrentStep = N).

4. Wizard Lifecycle & Role Center Onboarding Checklists

When a user steps through an assisted setup wizard, the extension must manage the lifecycle state within the Guided Experience framework so that the setup status indicator turns green (Completed) across both the Assisted Setup page and Onboarding Checklists.

Guided Experience Lifecycle Methods

• GuidedExperience.CompleteAssistedSetup(ObjectType, ObjectID): Marks the specified setup item as completed in the tenant database.
• GuidedExperience.IsAssistedSetupComplete(ObjectType, ObjectID): Returns a Boolean indicating whether the user or administrator has already completed the wizard.
• GuidedExperience.ResetAssistedSetup(ObjectType, ObjectID): Resets the item status back to Not Completed, allowing the wizard to be rerun from scratch.

Role Center Onboarding Checklists

Onboarding Checklists provide a curated list of getting-started tasks rendered in a prominent banner at the top of Role Centers for new users and evaluation companies. Checklists transform passive software exploration into active, structured onboarding journeys.

Checklist Characteristics & Administration

• Role-Centric Delivery: Checklists can be tailored to specific user profiles (e.g., an accountant sees financial setup steps, while a warehouse manager sees inventory location setup).
• Checklist Item Types: Tasks can link directly to an Assisted Setup wizard, a manual page, a Microsoft Learn URL, or an interactive In-App Tour.
• Progress Tracking: As users complete tasks, the checklist banner tracks completion percentage (e.g., 2 of 5 tasks completed), celebrating completion with visual feedback.
• Administrative Control: Tenant administrators can customize, reorder, add, or disable checklist items through the Checklist Administration page in the Web Client without modifying AL source code.