Dynamics 365 Business Central: obsoleting events

I’ve written a lot in the past about handling breaking schema changes on extensions and the best practice to use the ObsoleteState object property to signal to your developers or third-party ISV users of your extensions that you’re planning to remove something in your codebase. You can find articles here and here.

Today I want to write a quick post for talking about events and about a worst practice that I see someone is doing on their extensions. As you know, events are a foundamental key concept in the extension’s world. If you have extension A that defines some business logic and then you have extension B (that depends on A), from B you can interact with the business logic defined on A only by subscribing to events raised by extension A:

When you create an extension with AL language, you can define two types of events:

  • Business events: A business event is a custom event that is raised by AL code. It defines a formal contract that carries an implicit promise not to change in future releases.
  • Integration events: An integration event is also a custom event that is raised by AL code, like a business event, except that it does not carry the same promise of not changing.

The underlined text is extremely important in my opinion. If you declare that an event is a business event, you should not change it’s signature from version X to version X+1 of your extension. This is an error. Business events should be always documented together with the solution and if you’re an ISV you should provide their definition to your third-party users.

And what about if an event defined on version X will be never used in the future? You should never remove the event and release a version X+1 without this event. Instead, you should Obsolete the event on version X+1 and then gives the time to your extension’s users to react and adapt their code (yes, you can obsolete also events!).

As an example, imagine to have extension A that defines a business process in a codeunit. In this codeunit, you raise events for handling extensibility of your business process:

In extension B (that depends on A) you can attach to events raised by A by using event subscribers:

If you release version X+1 of your extension A and in this new version you decide to remove BusinessEvent1 (because it will be never used anymore), you can break other extensions:

What’s the best way to do this (if you really need to do this) then? On version X+1 of your extension A you can obsolete the BusinessEvent1 event as follows:

In this way your third-party users (other ISV and so on) will receive a warning on their code and they can act as needed:

Please remember this and use Obsolete property also on events if needed. This will guarantee you a more safe world 😉


  1. Good article. I would suggest another description for the obsoletion though. The description should help the developer, just telling that it will not exist is not very helpful.
    Please use a description that tells the developer how to handle the fact that an event will be removed. Something like ‘The event SomeNewBusinessEvent should be used instead’.

    Liked by 1 person

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.