_{BC AL Journey #16}

As we are developing customizations for Business Central there are times when we have to choose between hardcoding a value and providing a setting somewhere that it can be maintained. It is almost always better to provide values as configurable settings.

Often these customization configurations need a page for management. Business Central has a process for the creation and management of configuration pages. This allows you to add your configurations to the rest of the pages in an easy to find and manage location.

For this example, we are going to create a Settings Table, Page, and expose that page in the “Assisted Setup” menu within Business Central. Let’s define some requirements and get started.

Use Case

The user would like to define a default warranty to appear on the Sales Header for new Sales Quote documents.

Implementation

• Add a settings table to hold the default warranty value as a lookup to the warranty table.
• Create a settings page to allow configuration of the default warranty
• Add an event to the Sales Quote page to lookup the default warranty from the Settings table and update the Sales Header record
• Configure Assisted Setup system to display the settings page

Test Plan

• Open the Assisted Setup system
• Open the Warranty Settings page
• Set the Default Warranty value
• Create a new Sales Quote and verify that the warranty value matches the default

Creating the table and page are the easy part, and have already been covered, you can find what I created here:

• ARDSettings.Table.al
• ARDSettings.Page.al
• ARDSalesQuote.PageExt.al

The Assisted Setup menu is unique in that you don’t add your page to a table or anything to add it to the Assist Setup Menu. When the Assisted Setup page is loaded an event is triggered. Subscribing to this event gives you the opportunity to add your page to the list of pages as it is being generated.

Here is what that event looks like and how we register our settings page to be in that list. I’ve created the ARDSettingsManager.codeunit.al file.

[EventSubscriber(ObjectType::Codeunit, Codeunit::"Guided Experience", 'OnRegisterAssistedSetup', '', false, false)]
local procedure AddSetupWizard()
var
    GuidedExperience: Codeunit "Guided Experience";
    Language: Codeunit Language;
    AssistedSetupGroup: Enum "Assisted Setup Group";
    VideoCategory: Enum "Video Category";
    Info: ModuleInfo;
    CurrentGlobalLanguage: Integer;
    Title: Text[2048];
    ShortTitle: Text[50];
    Description: Text[1024];
    ExpectedDuration: Integer;
    ObjectTypeToRun: ObjectType;
    ObjectIDToRun: Integer;
    VideoURL: Text[250];
    HelpURL: Text[250];
begin
    ConfigureSettings();

    NavApp.GetCurrentModuleInfo(Info);
    CurrentGlobalLanguage := GLOBALLANGUAGE();

    Title := 'Warranty Setup';
    ShortTitle := 'Warranty Setup';
    Description := 'Setup for the Warranty Customizations';
    ExpectedDuration := 5;
    ObjectTypeToRun := ObjectType::Page;
    ObjectIDToRun := Page::ARD_Settings;
    AssistedSetupGroup := AssistedSetupGroup::Extensions;
    VideoURL := '';
    VideoCategory := VideoCategory::Uncategorized;
    HelpURL := 'http://AardvarkLabs.Blog';

    GuidedExperience.InsertAssistedSetup(Title, 
                                        ShortTitle, 
                                        Description,
                                        ExpectedDuration, 
                                        ObjectTypeToRun,
                                        ObjectIDToRun,
                                        AssistedSetupGroup,
                                        VideoURL, 
                                        VideoCategory,
                                        HelpURL);

    GLOBALLANGUAGE(Language.GetDefaultApplicationLanguageId());
    GLOBALLANGUAGE(CurrentGlobalLanguage);
end;

I’ve highlighted the critical lines that must be changed if you want to copy this into your own Code Unit.

Line 19 calls a Configure Settings procedure. It is important to ensure that the settings record exists and is ready for the page to load it. In this case it is a simple procedure that attempts to load the record and if it fails, creates a new settings record.

procedure ConfigureSettings(): Record ARD_Settings
var
    SettingsRecord: Record ARD_Settings;
begin
    if SettingsRecord.Get() = false then begin
        SettingsRecord.Init();
        SettingsRecord."ARD_No." := '';
        SettingsRecord.Insert();
    end;

    exit(SettingsRecord);
end;

From a programming standpoint, this is a singleton implementation where it ensures that a known single instance of a record exists. In most cases we don’t need more than one settings record.

Back to the event procedure, lines 24 – 33 are settings variables that will be passed to the procedure on line 35. I’ve broken all these variables out to make it easier to cut and paste this into other extensions. Thanks to simple naming, the variables are pretty self-explanatory. The important thing to note are the ObjectTypeToRun and the ObjectIdToRun are indicating that we are going to load a page, and it will be the ARD_Settings page created earlier.

When this is all compiled together, we can find the Warranty Settings in the Assisted Setup menu.

Clicking the link displays our Warranty Setup page.

I’ve selected Warranty 5 as my default. We could add a field to display the name of the selected Warranty as well as other bells and whistles.

When I create a new Sales Quote, I can see that the Warranty is automatically set to the Default Warranty from the settings file.

The code on the Sales Quote page looks like this:

trigger OnInsertRecord(BelowxRec: Boolean): Boolean
var
    Settings: Record ARD_Settings;
begin
    if Settings.Get() then
        Rec.ARD_WarrantyNo := Settings.ARD_DefaultWarranty;
end;

There is another event that registers for the Manual Setup. The configuration is nearly identical to the Assisted Setup. I’ve included the code in the ARDSettingsManager.codeunit.al file.

There are other similar systems available inside Business Central, for example, the “Service Connection” system utilizes a similar subscription-based menu.

I hope you now have an understanding of how the Assisted Setup pages can elevate your application allowing for easy management of settings needed by your customizations. There really is no reason to use static values for defaults when interfacing with the settings system is so easy. As always, more details can be found here: Designing Assisted Setup Guides – Business Central | Microsoft Learn