Skip to main content

BC Setup Wizard Generator

Automates creation of assisted setup wizards for Business Central setup tables following Guided Experience patterns.

Overview​

Generates complete NavigatePage setup wizards with step-based navigation, banner images, temporary records, and Guided Experience registration. Follows Microsoft patterns for assisted setup.

Complete code templates available in: references/code-templates.md

Prerequisites​

  • AL workspace with setup table
  • Setup table with fields to configure
  • (Optional) Setup page for post-wizard access

Workflow​

Step 1: Gather Information​

Collect from user:

  • Setup entity name (e.g., "Statistical Account")
  • Setup table name and ID
  • Prefix (e.g., "BCS")
  • Number of configuration steps (typically 2-4)
  • Field groups per step
  • Documentation URLs (video + written)

Step 2: Plan Wizard Steps​

Define wizard structure:

  • Step 1: Welcome - InstructionalText explaining wizard purpose
  • Step 2-N: Configuration - Field groups by logical category
  • Final Step: Review & Finish - Read-only summary of all settings

Example 3-step wizard:

  1. Welcome
  2. Attachments Settings (Step 1/2)
  3. Number Series Setup (Step 2/2)
  4. Review & Finish

Step 3: Create Wizard Page​

Create NavigatePage with:

  • PageType = NavigatePage
  • SourceTable = [Setup Table]
  • SourceTableTemporary = true ← Critical for unsaved workflow

Location: src/Page/[Prefix][Entity]SetupWizard.Page.al

See code-templates.md for complete structure.

Step 4: Add Banner Groups​

Add two banner groups at top of layout:

  • SetupWIPBanner: Visible during configuration steps
  • SetupFinishedBanner: Visible on review/finish step

Uses Media Repository records:

  • AssistedSetup-NoText-400px.png (WIP)
  • AssistedSetupDone-NoText-400px.png (Finished)

See code-templates.md for complete code.

Step 5: Add Step Groups​

Create one group per step with:

  • Visible property bound to StepXVisible boolean
  • InstructionalText for welcome/review steps
  • Field groups for configuration

Critical: Use step counters in captions for user guidance:

  • Caption = 'Attachments Settings 📎(Step 1/3)'

See code-templates.md for complete patterns.

Step 6: Add Navigation Actions​

Add three actions in area(Processing):

  • ActionBack: Enabled = BackActionEnabled, calls NextStep(true)
  • ActionNext: Enabled = NextActionEnabled, calls NextStep(false)
  • ActionFinish: Enabled = FinishActionEnabled, calls FinishAction()

All have InFooterBar = true for bottom positioning.

See code-templates.md for complete code.

Step 7: Add Page Triggers​

OnOpenPage:

  • Initialize temporary record from actual setup table
  • Call EnableControls() to show first step
  • Call LoadSetupBanner() to load banner images

OnQueryClosePage:

  • If FinishedProcess = true: Commit changes, mark setup complete
  • Else: Confirm user wants to exit without saving

See code-templates.md for complete implementation.

Step 8: Add Navigation Procedures​

Create local procedures:

ResetControls(): Reset all visibility booleans and action states

NextStep(Backwards: Boolean): Increment/decrement Step option, call EnableControls()

EnableControls(): Case statement routing Step to SetControlsStepXX()

SetControlsStepXX(): Set visibility for specific step, enable/disable actions

See code-templates.md for complete code.

Step 9: Add Data Management Procedures​

InitRecord():

  • Check if setup record exists
  • Create temporary record from existing or initialize new

CommitRecord():

  • Transfer temporary record to actual setup table
  • Insert if new, Modify if exists

FinishAction():

  • Set FinishedProcess = true
  • Close page (triggers OnQueryClosePage commit)

See code-templates.md for complete code.

Step 10: Add Setup Banner Loading​

LoadSetupBanner():

  • Get Media Repository records by name
  • Get Media Resources by reference
  • Set BannersVisible if media has value

See code-templates.md for complete code.

Step 11: Declare Variables​

Declare variables:

  • Record variables: Setup table, Media Repository (2), Media Resources (2)
  • Codeunit: GuidedExperience
  • Boolean: StepXVisible (per step), BackActionEnabled, NextActionEnabled, FinishActionEnabled, FinishedProcess, BannersVisible
  • Option: Step with values matching step groups

See code-templates.md for complete list.

Step 12: Create Registration Codeunit​

Create codeunit with event subscriber:

  • Subscribe to Codeunit::"Guided Experience"::OnRegisterAssistedSetup
  • Call AssistedSetup.InsertAssistedSetup() with:
    • Title and description labels
    • Time estimate (minutes)
    • Wizard page ID
    • Assisted Setup Group
    • Video URL and category
    • Documentation URL

Location: src/Codeunit/[Prefix][Entity]SetupManagement.Codeunit.al

See code-templates.md for complete code.

Step 13: Build and Test​

  1. Build project: al_build
  2. Publish: al_publish
  3. Test from:
    • Assisted Setup page (search "Assisted Setup")
    • Extension Management (Setup actions)
  4. Verify:
    • Navigation works (Back/Next/Finish)
    • Banners display correctly
    • Exit confirmation on close without finish
    • Changes saved on finish
    • Completion check marked

Troubleshooting​

Wizard doesn't appear in Assisted Setup​

Cause: Event subscriber not firing or registration failed
Fix: Check OnRegisterAssistedSetup event subscriber syntax, verify codeunit compiles without errors

Banners don't display​

Cause: Media Repository records not found or media reference empty
Fix: Check exact image names (AssistedSetup-NoText-400px.png, AssistedSetupDone-NoText-400px.png), verify Media Repository exists in base BC

Changes saved even when clicking X to close​

Cause: OnQueryClosePage not checking FinishedProcess flag
Fix: Ensure if FinishedProcess then condition exists, verify FinishAction sets flag before CurrPage.Close()

Steps don't navigate forward/backward​

Cause: Step option enum values don't match group names, or EnableControls case statement incomplete
Fix: Verify Step option has value for each step (Step10, Step20, Step30, etc.), check Case statement includes all values

Error on finish: "Record already exists"​

Cause: CommitRecord trying to Insert when record exists
Fix: Check if not SetupRecord.Get() then Insert else Modify pattern in CommitRecord procedure

Setup marked complete but changes not saved​

Cause: CommitRecord not called before CompleteAssistedSetup
Fix: Ensure OnQueryClosePage calls CommitRecord() before GuidedExperience.CompleteAssistedSetup()

Review step shows editable fields​

Cause: Review step groups missing Editable = false property
Fix: Add Editable = false to all field groups in final review step

Quick Reference​

Snippet: Use Waldo's tpagewizard3stepswaldo snippet for rapid scaffolding

Core Pattern: Temporary record → User edits → Finish commits → Mark complete

Key Properties:

  • Page: PageType = NavigatePage, SourceTableTemporary = true
  • Actions: InFooterBar = true
  • Groups: Visible = StepXVisible

Required Codeunits: Guided Experience (InsertAssistedSetup, CompleteAssistedSetup)

Media Files: AssistedSetup-NoText-400px.png, AssistedSetupDone-NoText-400px.png