Isolated Events, for all your isolated problems

Isolated Events is a new addition to Business Central 2022 Wave 1 (v20). An isolated event is transactional-isolated from what happens before and after it is run, including other subscribers. Check out the video:

https://youtu.be/5JkURNdzi74

In this video, Erik explores a feature introduced in Business Central version 20: isolated events. He explains the problem that led to their creation, walks through how they differ from regular (non-isolated) events using a flowchart, and demonstrates the behavior with a live coding example that subscribes to the OnCompanyOpenCompleted event.

The Problem: Errors in Event Subscribers

To understand why isolated events exist, we first need to understand how regular events work in AL — and what can go wrong.

When an event is raised — either from code or by the platform — the system finds all subscribers to that event and runs them sequentially. With a regular (non-isolated) event, if any subscriber throws an error:

  • Execution stops immediately.
  • Other event subscribers that haven’t run yet never get called.
  • The error propagates back to the caller, potentially stopping whatever process raised the event.

This became a serious issue with one specific event in the system: OnCompanyOpen. If an event subscriber to OnCompanyOpen raised an error, it could block users from logging in entirely. In the worst case, you couldn’t even install or uninstall extensions because the login process itself was broken.

As Erik puts it: “We might be the ones who created this problem by doing things on OnCompanyOpen that we were not supposed to do — but Microsoft has to fix it.”

The fix was to deprecate OnCompanyOpen and replace it with OnCompanyOpenCompleted, which is an isolated event. You can see the deprecation notice directly in the code: “Method OnCompanyOpen is marked for removal. Reason: Replaced by OnCompanyOpenCompleted to avoid errors in login.”

How Isolated Events Work

Erik walks through a flowchart that illustrates the lifecycle of an isolated event compared to a regular one. Here are the key differences:

1. Each Subscriber Runs in Its Own Transaction

When an isolated event is raised, the system starts a new transaction for each subscriber. This is the first major difference: because a new transaction must be started, an isolated event can only be successfully triggered if there is no open write transaction at the time of the call.

2. Errors Are Contained

If a subscriber to an isolated event raises an error:

  • The transaction for that subscriber is rolled back.
  • Execution continues to the next subscriber.
  • The error does not propagate back to the caller.

Compare this to a regular event, where an error would halt everything. With isolated events, even if one subscriber fails, the others still get their chance to run.

3. Successful Subscribers Are Committed Individually

If a subscriber completes without error, its transaction is committed before moving on to the next subscriber. This means each subscriber’s work is independent — one subscriber’s success or failure has no effect on the others.

Demo: Subscribing to OnCompanyOpenCompleted

Erik demonstrates the behavior by creating a subscriber to the isolated event OnCompanyOpenCompleted that randomly throws an error about 20% of the time:

codeunit 50100 "Test"
{
    [EventSubscriber(ObjectType::Codeunit, Codeunit::"Company Triggers", 'OnCompanyOpenCompleted', '', true, true)]
    local procedure MyProcedure()
    begin
        if random(10) < 3 then
            error('Hello Youtube! 2');
    end;
}

Because OnCompanyOpenCompleted is an isolated event, even when the error fires, users can still log in. The error is rolled back and contained — it doesn't block the login process or prevent other subscribers from running.

Creating Your Own Isolated Events

You can create your own isolated events by adding a boolean parameter to the event declaration. The syntax for a business event looks like this:

[BusinessEvent(true)] // IncludeSender = true
// But now you can also specify isolated:
[BusinessEvent(true, true)] // Second boolean = Isolated

There's an important prerequisite when raising an isolated event from your own code: you must not be in an open write transaction. If you are, you need to commit first:

// Your long and complicated code here...

Commit(); // Finalize your transaction

MyIsoEvent(); // Now safe to raise the isolated event

Erik frames this as a way to offer low-risk events to your subscribers. If you know that a system-based commit is going to happen anyway after your code returns, you can anticipate that commit, issue it explicitly, and then raise an isolated event. This way, no matter what subscribers do, they cannot affect the result of your own work.

Discoverability: A Current Limitation

One thing Erik calls out as a gap in the current tooling is discoverability. When you're looking at an event subscriber, there's no obvious visual indicator telling you whether the event you're subscribing to is isolated or not. There's no special icon, no comment, and no marking in the subscriber attribute itself. You have to navigate to the event's declaration in the source codeunit to find out.

For platform-triggered events like OnCompanyOpenCompleted, there's no code navigation available at all, making it even harder to discover. Erik suggests it would be helpful if the tooling provided a different icon or annotation to make isolated events immediately recognizable.

Summary

Isolated events were introduced in Business Central version 20 to solve a real and painful problem — event subscribers that could break critical system processes like login. Here's what makes them different from regular events:

  • Each subscriber runs in its own transaction — errors are rolled back, successes are committed individually.
  • Errors don't propagate — if one subscriber fails, the others still run, and the caller is unaffected.
  • No open write transaction — isolated events can only be raised when there's no active write transaction.
  • Low-risk by design — subscribers cannot interfere with each other or with the code that raised the event.

While Erik notes he doesn't foresee himself using isolated events extensively in his own code, they serve a clear purpose: protecting critical execution paths from misbehaving subscribers. If you're building an API or framework where stability matters more than tight transactional coupling, isolated events are a valuable tool to have in your arsenal.

Picture of hougaard

hougaard