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.