bc-setup-wizard-generator

name

bc-setup-wizard-generator

description

Generates assisted setup wizard pages for Business Central setup tables following Guided Experience patterns. Creates NavigatePage with step-based navigation using visibility controls, banner images (WIP/Finished from Media Repository), temporary source table, footer actions (Back/Next/Finish with InFooterBar), OnOpenPage trigger (InitRecord, EnableControls, LoadSetupBanner), OnQueryClosePage trigger with unsaved changes confirmation, navigation procedures (NextStep with Step Option variable, EnableControls with Case statement, SetControlsStepXX boolean updates), commit procedure using TransferFields pattern, and registration codeunit with OnRegisterAssistedSetup event subscriber for Guided Experience. Integrates with Assisted Setup page and Extension Management. Supports multi-step workflows with welcome step, configuration step(s), and review/finish step. Uses InstructionalText for user guidance. Completes setup via GuidedExperience.CompleteAssistedSetup. Use when creating setup wizards, implementing assisted setup for extensions, adding guided configuration to modules, creating multi-step setup pages, registering with Guided Experience framework, or building NavigatePage wizards with step navigation.

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