Business central assisted setup

Business Central Assisted Setup

Purpose

Build Microsoft-style setup assistants for Business Central AL extensions by combining:

• A setup object, usually a NavigatePage wizard or setup card page.
• A registration codeunit subscribing to Codeunit::"Guided Experience" events.
• Codeunit 1990 "Guided Experience" calls to insert, run, complete, reset, or check setup state.
• Optional Confirm() prompts for first-run initialization.

First Inspect The Project

Before editing, inspect existing AL patterns:

• Search for Guided Experience, Assisted Setup, NavigatePage, InsertAssistedSetup, InsertManualSetup, CompleteAssistedSetup, app.json, and existing setup pages.
• Reuse the extension's object ID range, naming conventions, captions, suffixes, permissions, and folder layout.
• Prefer adding a narrow setup wizard plus registration codeunit. Do not rewrite unrelated setup pages.

Implementation Pattern

Use this shape unless the project already has a better local pattern:

1. Create or reuse a setup/wizard page.
2. Create a registration codeunit that subscribes to OnRegisterAssistedSetup or OnRegisterManualSetup.
3. In the subscriber, call GuidedExperience.Exists(...); if false, call InsertAssistedSetup(...) or InsertManualSetup(...).
4. Set IsPrimarySetup = true for the main extension setup so Business Central can expose "Set up this app" from extension management.
5. In the setup page, run initialization behind an explicit user action or a Confirm() prompt.
6. After successful setup, call GuidedExperience.CompleteAssistedSetup(ObjectType::Page, Page::<WizardPageName>).

Assisted Setup Card Template

Use this for a card in the standard Assisted Setup page.

codeunit 50110 "My App Guided Experience"
{
    [EventSubscriber(ObjectType::Codeunit, Codeunit::"Guided Experience", 'OnRegisterAssistedSetup', '', true, true)]
    local procedure OnRegisterAssistedSetup()
    var
        GuidedExperience: Codeunit "Guided Experience";
        GuidedExperienceType: Enum "Guided Experience Type";
        AssistedSetupGroup: Enum "Assisted Setup Group";
        VideoCategory: Enum "Video Category";
    begin
        if GuidedExperience.Exists(
            GuidedExperienceType::"Assisted Setup",
            ObjectType::Page,
            Page::"My App Setup Wizard")
        then
            exit;

        GuidedExperience.InsertAssistedSetup(
            'Set up My App',
            'My App',
            'Set up the required configuration for My App.',
            5,
            ObjectType::Page,
            Page::"My App Setup Wizard",
            AssistedSetupGroup::Extensions,
            '',
            VideoCategory::Uncategorized,
            '',
            true);
    end;
}

Adjust:

• Titles and descriptions to be user-facing, short, and specific.
• ExpectedDuration to a realistic minute count below 30000.
• AssistedSetupGroup to the closest available enum value in the target BC version.
• VideoUrl, VideoCategory, and HelpUrl only when real resources exist.
• The last Boolean overload only if the target runtime exposes IsPrimarySetup.

Wizard Page Template

Use NavigatePage for step-by-step setup. Keep wizard logic explicit and durable; do not put irreversible work in OnOpenPage unless it is guarded.

page 50110 "My App Setup Wizard"
{
    PageType = NavigatePage;
    Caption = 'Set up My App';
    ApplicationArea = All;
    UsageCategory = Administration;

    layout
    {
        area(content)
        {
            group(Welcome)
            {
                Caption = '';

                field(InstructionText; InstructionText)
                {
                    ApplicationArea = All;
                    Editable = false;
                    ShowCaption = false;
                    MultiLine = true;
                }
            }
        }
    }

    actions
    {
        area(processing)
        {
            action(Finish)
            {
                ApplicationArea = All;
                Caption = 'Finish';
                InFooterBar = true;
                Image = Approve;

                trigger OnAction()
                begin
                    RunInitialSetup();
                    CompleteSetup();
                    CurrPage.Close();
                end;
            }
        }
    }

    trigger OnOpenPage()
    begin
        InstructionText := 'This wizard will help you set up My App.';
    end;

    local procedure RunInitialSetup()
    begin
        // Create default records, validate required setup, or call setup codeunits here.
        // Make this idempotent so rerunning the wizard does not duplicate data.
    end;

    local procedure CompleteSetup()
    var
        GuidedExperience: Codeunit "Guided Experience";
    begin
        GuidedExperience.CompleteAssistedSetup(ObjectType::Page, Page::"My App Setup Wizard");
    end;

    var
        InstructionText: Text;
}

Initial Setup Confirmation

To mimic the Microsoft-style "Do you want to run the initial setup?" dialog, use Confirm() in the setup object before running initialization.

trigger OnOpenPage()
begin
    if not Confirm('Do you want to run the initial setup?', false) then
        CurrPage.Close();

    InstructionText := 'This wizard will create the default setup records.';
end;

Prefer calling the actual initialization from Finish or another explicit action. If initialization must run immediately after Confirm(), make it idempotent and handle failures with clear Error() messages.

Manual Setup Variant

Use manual setup when the item should open a normal setup page rather than a guided wizard.

[EventSubscriber(ObjectType::Codeunit, Codeunit::"Guided Experience", 'OnRegisterManualSetup', '', true, true)]
local procedure OnRegisterManualSetup()
var
    GuidedExperience: Codeunit "Guided Experience";
    ManualSetupCategory: Enum "Manual Setup Category";
begin
    GuidedExperience.InsertManualSetup(
        'My App Setup',
        'My App',
        'Configure My App settings.',
        5,
        ObjectType::Page,
        Page::"My App Setup",
        ManualSetupCategory::Extensions,
        'my app,setup,configuration',
        true);
end;

Check the target BC version for the exact overload. If the overload with IsPrimarySetup is unavailable, use the supported overload and document the limitation.

Completion And Rerun Behavior

Use these Guided Experience methods as needed:

• IsAssistedSetupComplete(ObjectType, ObjectID) before prompting users.
• AssistedSetupExistsAndIsNotComplete(ObjectType, ObjectID) to decide whether to nudge setup.
• CompleteAssistedSetup(ObjectType, ObjectID) after successful setup.
• ResetAssistedSetup(ObjectType, ObjectID) only for intentional reset actions or test helpers.
• Run(GuidedExperienceType::"Assisted Setup", ObjectType::Page, Page::<Wizard>) to launch a registered guide.
• OpenAssistedSetup() to open the standard Assisted Setup list.

If handling reruns matters, subscribe to OnReRunOfCompletedAssistedSetup and set Handled := true only when replacing default behavior deliberately.

Quality Checklist

Before finishing:

• Confirm object IDs are inside app.json ranges.
• Confirm the project compiles against the target BC runtime; enum values and overloads can differ by version.
• Ensure initialization is idempotent: rerunning setup must not duplicate default data.
• Mark the guide complete only after all required setup succeeds.
• Keep all user-facing text in labels if the project localizes strings.
• Add permission set changes if setup writes to protected tables.
• Avoid using internal tables such as Guided Experience Item directly; use Codeunit 1990 "Guided Experience".

Explaining The Pattern

When explaining how Microsoft-style setup assistants work, summarize it this way:

"The visible cards are not custom UI from the extension. They are entries registered into Business Central's Guided Experience system. The extension subscribes to Guided Experience registration events and inserts an Assisted Setup or Manual Setup item. When a user opens the card, BC runs the registered page/codeunit. The page can show a Confirm() dialog, perform initialization, and then call CompleteAssistedSetup() to update completion state."