Onboarding Checklist – Hacking Session

In this video, I go poking around in the new onboarding checklist functionality to figure out how it works and if it’s usable by others besides Microsoft (Spoiler alert, it is).

https://youtu.be/5vgK2ap1cIc

In this hacking session, Erik explores the onboarding checklist feature introduced in Business Central version 18. This guided experience appears on the Role Center when users create a new company, walking them through setup steps. Erik digs into the source code to understand how it works under the hood and demonstrates how you can add your own checklist items from a custom extension.

The Onboarding Checklist Experience

When you create a new company in Business Central v18 and open it for the first time, you’re greeted with a “Get Started” banner: “Hi Erik, ready to set up your business? We prepared a few activities to get you and your team quickly started.”

Clicking “Get Started” reveals a checklist with several steps:

  • Company Details – launches the assisted setup for a new company
  • Update Users – synchronizes user entitlements from Microsoft 365
  • Migrate Data – estimated at 15 minutes (“perhaps a bit optimistic,” Erik notes)
  • Microsoft Learn – estimated at 10 minutes

Each step shows an estimated completion time, and you can mark items complete, skip them, or revisit them later. Essentially, the checklist acts as a curated set of pointers to different spots in the system that a new user needs to configure.

Digging Into the Source Code

Erik starts by looking at the Business Manager Role Center (Page 9022) to understand how the checklist appears. Interestingly, the usual headline control — the one that shows things like “biggest orders” — gets replaced by the checklist banner. There’s nothing in the Role Center page object itself that references the onboarding checklist.

Using the AL Code Outline extension (which Erik describes as “fantastic” and says he uses “hourly, not just daily”), he searches for “checklist” across the base app objects and finds a codeunit called Checklist Events (object 1997).

This codeunit subscribes to the OnAfterLogInStart event from LogInManagement. When a user logs in via a web or desktop client, it checks whether the checklist should be initialized, and if so, calls Checklist.Insert to register each checklist item with parameters like:

  • Guided experience type (Assisted Setup, Manual Setup, etc.)
  • Object type and ID to run
  • An order ID for sequencing
  • A temporary record of profiles (roles) to show the checklist for
  • A boolean for whether everyone must complete the step or just one person

The System Application Layer

The actual Checklist codeunit isn’t in the base app — it lives in the System Application. Since the System Application is open source, Erik heads to GitHub to read the full source. The key method signature is:

Checklist.Insert(GuidedExperienceType, ObjectType, ObjectId, OrderId, TempAllProfile, ShouldEveryoneComplete)

There’s also an overload that lets you specify a particular user who should complete the step.

The Checklist Banner Page

Erik finds a Checklist Banner page in the System Application. This page has Extensible = false, and includes a telling comment: “Do not change the name of any of the fields on this page. The client will not be able to render the page properly otherwise.”

This reveals that the checklist UI is partially hard-coded on the client side. The client expects specific field names like Title, Header, Description, TitleCollapsed, and HeaderCollapsed. The banner appears to show up automatically on any Role Center, replacing the headline control, without giving developers a way to prevent or customize the rendering.

The Hack: Adding a Custom Checklist Item

With this understanding, Erik builds a simple extension that adds the General Ledger Setup page as a new checklist item. Here’s the complete codeunit:

codeunit 50100 "Our Checklist Events"
{

    [EventSubscriber(ObjectType::Codeunit, Codeunit::LogInManagement, 'OnAfterLogInStart', '', true, true)]
    local procedure InitializeChecklist()
    var
        TempAllProfile: Record "All Profile" temporary;
        Checklist: Codeunit Checklist;
        GuidedExperienceType: Enum "Guided Experience Type";
    begin
        GetRoles(TempAllProfile);

        Checklist.Insert(GuidedExperienceType::"Manual Setup", ObjectType::Page, Page::"General Ledger Setup", 1500, TempAllProfile, false);
    end;

    local procedure GetRoles(var TempAllProfile: Record "All Profile" temporary)
    begin
        AddRoleToList(TempAllProfile, Page::"Business Manager Role Center");
    end;

    local procedure AddRoleToList(var TempAllProfile: Record "All Profile" temporary; RoleCenterID: Integer)
    var
        AllProfile: Record "All Profile";
    begin
        AllProfile.SetRange("Role Center ID", RoleCenterID);
        if AllProfile.FindFirst() then begin
            TempAllProfile.TransferFields(AllProfile);
            TempAllProfile.Insert();
        end;
    end;
}

The approach is straightforward:

  1. Subscribe to the login event — the same OnAfterLogInStart event that Microsoft’s own checklist code uses.
  2. Build a list of roles — use a temporary All Profile record to specify which Role Centers should display the checklist item (in this case, the Business Manager Role Center).
  3. Insert the checklist item — call Checklist.Insert with the guided experience type set to Manual Setup, pointing to the General Ledger Setup page, with an order ID of 1500 (placing it between the existing Microsoft items at 1000 and 2000).

The app.json targets the cloud runtime with Business Central 18.0.0.0:

{
  "id": "2bb44f88-a63e-4bf1-af88-1b445d3d6e11",
  "name": "checklist hacking",
  "publisher": "Default publisher",
  "version": "1.0.0.0",
  "platform": "1.0.0.0",
  "application": "18.0.0.0",
  "idRanges": [
    {
      "from": 50100,
      "to": 50149
    }
  ],
  "showMyCode": true,
  "target": "Cloud",
  "runtime": "7.0"
}

Testing the Result

After deploying the extension, Erik discovers an important detail: the checklist only initializes once per company. Opening the company where he’d already seen the checklist showed no changes. But switching to a different company that hadn’t been initialized yet, the new “General Ledger Setup” item appeared in the checklist alongside the standard Microsoft items.

The description displayed — “Define how to manage your company’s finances” — was pulled automatically, likely from the page’s tooltip or caption metadata. Clicking “Start” on the item opens the General Ledger Setup page as expected.

Observations and Critiques

Erik notes several things worth keeping in mind:

  • The headline gets replaced. When the onboarding checklist is active, the usual Role Center headline control disappears. There doesn’t appear to be a way to prevent this.
  • Hard-coded client rendering. The checklist banner page is rendered by client-side code that expects specific field names. This breaks the tradition of Business Central being a fully open, extensible platform.
  • Non-extensible pages. Many System Application pages are marked with Extensible = false. While this makes sense for pages containing sensitive information (like CRM password configuration), it’s overly restrictive for pages like the checklist banner.
  • One-time initialization. The checklist appears to initialize only once per company. If your extension is installed after the company has already been set up, additional work may be needed to get your items to appear.

Conclusion

The onboarding checklist in Business Central v18 is a welcome feature that helps guide users through initial company setup. More importantly for developers, it’s extensible — you can add your own checklist items by subscribing to the login event and calling Checklist.Insert. If your app requires users to configure something when setting up a new company, this is a great way to surface that setup step right where users will see it.

That said, the implementation is a mix of open and closed. The data layer and event model are accessible from AL, but the UI rendering is hard-coded on the client side. Erik would love to see Microsoft make this more generic — not just for Role Centers, but potentially for any page where a first-time checklist could guide users. For now, though, the ability to hook into the existing checklist is a practical and valuable capability for app developers.

Picture of hougaard

hougaard