Dynamics 365 Business Central: How to deprecate external business events (ExternalBusinessEvent)

Hi, Readers.
Today I would like to talk about how to deprecate external business events (ExternalBusinessEvent).

Business events provide our partners and customers a mechanism for notifying and triggering their external systems (Dataverse and non-Dataverse) when actions are done on Business Central. The external systems can react and perform other actions in response. With Dataverse, partners and customers can use Power Automate to subscribe to Business Central for its business events and react on other apps in its ecosystem, such as Dynamics 365 Sales or Customer Service, and others built using Power Apps. They can also react on non-Dataverse systems, such as non-Microsoft warehouse management, fulfillment, and e-invoicing services. More details: Business events on Business Central (preview)

Business Central catalog of business events: The following table describes the business events in Business Central catalog. These business events are readily available in version 22.2 and later but must be implemented in an extension in version 22.0 and 22.1

These are defined in AL. These codes are stored in the Exclude_Business_Events extension.
PS: How to list all installed extensions/apps in your Business Central environment (Including hidden apps – “_Exclude_……”)

We can add dependencies settings in the app.json file to download its symbol file.

  "dependencies": [
    {
      "id": "6f2c034f-5ebe-4eae-b34c-90a0d4e87687",
      "name": "_Exclude_Business_Events_",
      "publisher": "Microsoft",
      "version": "24.0.0.0"
    }
  ],

For example, Sales order released:

Customer blocked:

How do we understand the standard code here? Let’s go back to Sales order released. Simply put, there are three steps.
1. Defining External Business Events

ExternalBusinessEvent(Name: Text, DisplayName: Text, Description: Text, Category: Enum, [Version: Text])
Specifies that the method is published as an external business event.

2. Subscribe to the event to specify when it needs to be triggered.

EventSubscriber(ObjectType: ObjectType, ObjectId: Integer, EventName: Text, ElementName: Text, SkipOnMissingLicense: Boolean, SkipOnMissingPermission: Boolean)
Specifies the event to which the method subscribes.

3. Put the procedure created in step 1 into the procedure in step 2.

PS: If you need more detailed instructions, you can refer to Microsoft documentation, Build and install an extension for custom business events.
Sample code provided by Microsoft:

enumextension 50101 MyEnumExtension extends EventCategory
{
   value(0; "Sales")
   {
   }
}

codeunit 50102 MyCodeunit 
{ 
   trigger OnRun()
   begin
   end; 

   [ExternalBusinessEvent('salesorderposted', 'Sales order posted', 'Triggered when sales order has been posted', EventCategory::"Sales")]
   [RequiredPermissions(PermissionObjectType::TableData, Database::"Sales Header", 'R')] // optional
   procedure SalesOrderPosted(salesOrderId: Guid; customerName: Text; orderNumber: Text)
   begin
   end;
   
   [EventSubscriber(ObjectType::Page, Page::"Sales Order", 'OnPostDocumentBeforeNavigateAfterPosting', '', true, true)] 
   local procedure OnPostDocument(var SalesHeader: Record "Sales Header"; var PostingCodeunitID: Integer; var Navigate: Enum "Navigate After Posting"; DocumentIsPosted: Boolean; var IsHandled: Boolean) 
   begin
      SalesOrderPosted(SalesHeader.SystemId, SalesHeader."Sell-to Customer Name", SalesHeader."No."); 
   end;
}

More details: Dynamics 365 Business Central: OnValidate (Field) Trigger in Power Automate (Trigger a flow when a field is modified) – Business events

For long-lived or widely distributed applications, you might need to phase out certain events over time, ensuring that external integrations have sufficient notice to update their subscriptions. This process is managed by deprecating external business events in a predictable way so that consumers of the event are informed and encouraged to transition to new or replacement events. The approach for deprecating an external business event is similar to the standard deprecation process for procedures.
APPLIES TO: Business Central 2025 release wave 1 (v26) and later.

First, mark the event as obsolete pending.

1. Decorate the procedure with the [Obsolete('<Reason>','<Tag>')] attribute, as you would for any other procedure that is pending deprecation.
2. Prefix the DisplayName of the ExternalBusinessEvent attribute with an [OBSOLETE] marker. This ensures that the obsoletion is reflected in the name, and external subscribers see the deprecation notice.

Or

Here is a simple example:

In Power Automate:

Then, remove the event in a future version. Great, give it a try!!!😁

More details: Deprecate external business events

END

Hope this will help.

Thanks for reading.

ZHU