How to Create Assisted Setups in Business Central

Updated: Aug 4, 2020

Assisted Setup is a wizard page to help Business Central User setting up a module. When you are creating an extension for Business Central, you must consider creating one or more Assisted Setups for your extension.


Wizard Page:

Assisted Setup is nothing but a wizard page (guided page) containing one or more steps to help Business Central User to configure setups.


Page layout:

Page contains at least two steps, start and finish (welcome and thanks) steps. Each step is a field group and visibility which are controlled by a boolean variable or a step number condition.


For example, VAT Setup Wizard contains the following steps:

  • Welcome to VAT Setup

  • VAT Business Posting Groups

  • VAT Product Posting Setup

  • Assign VAT Setup to Customer, Vendor, and Item Templates

  • Manual setup required

  • That''s it!

Actions:

There will be Back, Next, Finish actions to navigate between steps, again actions are enabled or disabled based on the state of some variables.

For example, Back is disabled in the first step, and Next is disabled in the last step.


Assisted Setup [Codeunit 3725]

Assisted Setup is system codeunit which allows you to register your wizard page and execute your wizard page when the User opens it from Assisted Setup.


Assisted Setup codeunit has the following events:

  • OnRegister - Triggered when Assisted Setup list page is being opened.

  • OnReRunOfCompletedSetup - Triggered if the previously completed Assisted Setup is being run again.

  • ·OnBeforeOpenRoleBasedSetupExperience - Triggered when Assisted Setup is opened from Navigation bar >> Settings >> Assisted setup

  • OnAfterRun - Triggered after the Assisted Setup has finished.


Best Practices:

  • First step should contain Welcome message, and explanation of the wizard page.

  • All actions (Back, Next, Finish) should validate User Inputs before navigating it to the next or back step.

  • Only the Finish step should write data into actual tables. This is very critical because User can close the wizard page any time. Also, you should keep data in intermediate tables so that if the User opens the wizard page again, he doesn’t need to enter the same data again.


Code Sample

Let us take a basic example; we will create an Assisted Setup to setup Sales Order, and Sales Invoice document Number Series.

We need minimum two objects; a codeunit to subscribe Assisted Setup codeunit events, and a page for the wizard page.


Assisted Setup Subscribers [NoSeriesSetupSubscribers.Codeunit.al]

We are subscribing Assisted Setup events to register our “No. Series Setup Wizard” page.


codeunit 50120 "No. Series Setup Subscribers"
{
    var
        Info: ModuleInfo;
        SetupWizardTxt: Label 'Set up Sales No. Series';
        x: Codeunit "Assisted Setup Subscribers";

    [EventSubscriber(ObjectType::Codeunit, Codeunit::"Assisted Setup", 'OnRegister', '', false, false)]
 local procedure Initialize()
 var
        AssistedSetup: Codeunit "Assisted Setup";
        Language: Codeunit Language;
        CurrentGlobalLanguage: Integer;
 begin
        CurrentGlobalLanguage := GlobalLanguage;
        AssistedSetup.Add(
            GetAppId(),
 Page::"No. Series Setup Wizard",
            SetupWizardTxt,
            "Assisted Setup Group"::GettingStarted,
 '',
            "Video Category"::Uncategorized,
 '');

        GlobalLanguage(Language.GetDefaultApplicationLanguageId());

 //Adds the translation for the name of the setup.
        AssistedSetup.AddTranslation(
 Page::"No. Series Setup Wizard",
            Language.GetDefaultApplicationLanguageId(),
            SetupWizardTxt);
        GlobalLanguage(CurrentGlobalLanguage);
 end;

 local procedure GetAppId(): Guid
 var
        EmptyGuid: Guid;
 begin
 if Info.Id() = EmptyGuid then
            NavApp.GetCurrentModuleInfo(Info);

 exit(Info.Id());
 end;
}



Wizard Page [NoSeriesSetupWizard.Page.al]

This page contains 3 steps, first step contains introduction, second step takes inputs from the User, and the third setup will finish the wizard by updating fields in Sales & Receivable Setup table.


page 50120 "No. Series Setup Wizard"
{
    Caption = 'Sales No. Series Setup';
    PageType = NavigatePage;
    SourceTable = "Sales & Receivables Setup";
    SourceTableTemporary = true;

    layout
    {
        area(content)
        {
            group(FirstStep)
            {
                Visible = CurrentPage = 1;
                group("Welcome to Email Setup")
                {
                    Caption = 'Welcome to Sales Number Series Setup';
                    Visible = CurrentPage = 1;
                    ;
                    group(Control18)
                    {
                        InstructionalText = 'You can setup Sales Order, Sales Invoice document Number Series.';
                        ShowCaption = false;
                    }
                }
                group("Let's go!")
                {
                    Caption = 'Let''s go!';
                    group(Control22)
                    {
                        InstructionalText = 'Choose Next so you can configure Number Series for Sales Orders, Sales Invoices.';
                        ShowCaption = false;
                    }
                }
            }

            group(Step2)
            {
                Caption = '';
                Visible = CurrentPage = 2;
                group("Para2.1")
                {
                    Caption = 'Select Number Series for Sales Orders';
                    field("Order Nos."; Rec."Order Nos.")
                    {
                        ApplicationArea = Basic, Suite;
                        ShowCaption = false;
                    }
                }
                group("Para2.2")
                {
                    Caption = 'Select Number Series for Sales Invoices';
                    field("Invoice Nos."; Rec."Invoice Nos.")
                    {
                        ApplicationArea = Basic, Suite;
                        ShowCaption = false;
                    }
                }
            }
            group(Step3)
            {
                ShowCaption = false;
                Visible = CurrentPage = 3;
                group("That's it!")
                {
                    Caption = 'That''s it!';
                    group(Control25)
                    {
                        InstructionalText = 'To update Number Series for sale documents, choose Finish.';
                        ShowCaption = false;
                    }
                }
            }
        }
    }

    actions
    {
        area(processing)
        {
            action(BackAction)
            {
                ApplicationArea = Basic, Suite;
                Caption = '&Back';
                Enabled = (CurrentPage > 1) AND (CurrentPage < 3);
                Image = PreviousRecord;
                InFooterBar = true;
                Promoted = true;

                trigger OnAction()
                begin
                    CurrentPage := CurrentPage - 1;
                    CurrPage.Update;
                end;
            }
            action(NextAction)
            {
                ApplicationArea = Basic, Suite;
                Caption = '&Next';
                Enabled = (CurrentPage >= 1) AND (CurrentPage < 3);
                Image = NextRecord;
                InFooterBar = true;
                Promoted = true;

                trigger OnAction()
                begin
                    case CurrentPage of
                        2:
                            begin
                                Rec.TestField("Order Nos.");
                                Rec.TestField("Invoice Nos.");
                            end;
                    end;

                    CurrentPage := CurrentPage + 1;
                    CurrPage.Update(false);
                end;
            }
            action(FinishAction)
            {
                ApplicationArea = Basic, Suite;
                Caption = '&Finish';
                Enabled = CurrentPage = 3;
                Image = Approve;
                InFooterBar = true;
                Promoted = true;

                trigger OnAction()
                var
                    AssistedSetup: Codeunit "Assisted Setup";
                begin
                    SalesSetup.Get();
                    SalesSetup."Order Nos." := Rec."Order Nos.";
                    SalesSetup."Invoice Nos." := Rec."Invoice Nos.";
                    SalesSetup.Modify();

                    AssistedSetup.Complete(PAGE::"No. Series Setup Wizard");
                    CurrPage.Close;
                end;
            }
        }
    }

    trigger OnInit()
    begin
        SalesSetup.Get();
        Rec := SalesSetup;
        CurrentPage := 1;
    end;

    trigger OnOpenPage()
    begin
        Insert;
    end;

    trigger OnQueryClosePage(CloseAction: Action): Boolean
    var
        AssistedSetup: Codeunit "Assisted Setup";
        Info: ModuleInfo;
    begin
        if CloseAction = Action::OK then
            if AssistedSetup.ExistsAndIsNotComplete(Page::"No. Series Setup Wizard") then
                if not Confirm(NAVNotSetUpQst, false) then
                    Error('');
    end;

    var
        SalesSetup: Record "Sales & Receivables Setup";
        CurrentPage: Integer;
        NAVNotSetUpQst: Label 'The Sales No. Series Setup has not been set up.\Are you sure you want to exit?';
}

Assisted Setup in Action




Conclusion

Assisted Setup are the best way to ask your User to configure setup data for your extension. You don’t need to provide training to your Users, because all the steps in the Assisted Setup are intuitive and guided with instructions.

You can download source code from GitHub.


#MsDyn365 #MsDyn365BC #BusinessCentral

1,025 views0 comments