Business Central Event Subscriber Patterns for AL Developers
AL subscriber patterns, checked against Microsoft Learn and version 29

On this page
A Business Central event subscriber is an AL method, marked with the EventSubscriber attribute inside a codeunit, that runs when a published event is raised. It lets an extension add behavior to standard code flows without modifying Microsoft's base application. Safe subscribers pick the most specific event, stay small, avoid unplanned commits, protect side effects from retries and treat IsHandled as a last resort.
This guide is for AL developers and technical leads who maintain Business Central extensions. It covers 2026 release wave 2 (version 29).
Review inherited subscribers. The free BC Environment Snapshot is one hour on a screen share with a Business Central consultant, then a written summary of your environment within five business days.
Choose the right event
Choose the smallest, most explicit extension boundary that preserves the publisher's business invariants.
Business, integration, and internal events in AL are published by event publisher methods that someone wrote deliberately. Trigger events are published by the runtime for table and page operations. Prefer an event whose name and parameters directly represent the business point you need. A late, generic trigger event may force the subscriber to reconstruct context that an earlier business event already provides.
Microsoft's guide to types of events for extensibility rates events before or after a large operation, such as OnAfterPostSalesDoc, as high value, and handled events as low value.
Read the publisher and surrounding code. Determine whether the event runs before or after validation, inside a transaction, once per document, or once per line. An event name alone does not describe all of those semantics.
Reference objects by name in the EventSubscriber attribute
Microsoft's EventSubscriber attribute reference recommends using an object name rather than an ID. For table events, use Database:: rather than Table::.
Skeleton in AL; the queue implementation is omitted. It compiles against Business Central 29.0 symbols.
codeunit 50110 "BA Sales Subscribers"
{
[EventSubscriber(ObjectType::Codeunit, Codeunit::"Sales-Post",
'OnAfterPostSalesDoc', '', false, false)]
local procedure OnAfterPostSalesDoc(
var SalesHeader: Record "Sales Header";
var GenJnlPostLine: Codeunit "Gen. Jnl.-Post Line";
SalesShptHdrNo: Code[20];
RetRcpHdrNo: Code[20];
SalesInvHdrNo: Code[20];
SalesCrMemoHdrNo: Code[20];
CommitIsSuppressed: Boolean;
InvtPickPutaway: Boolean;
var CustLedgerEntry: Record "Cust. Ledger Entry";
WhseShip: Boolean;
WhseReceiv: Boolean;
PreviewMode: Boolean)
begin
if PreviewMode then
exit;
QueueFollowUp(SalesHeader.SystemId, SalesInvHdrNo);
end;
local procedure QueueFollowUp(SourceSystemId: Guid; PostedInvoiceNo: Code[20])
begin
// Delegate to the app's durable, idempotent queue implementation.
end;
}The signature matches the version 29 Sales-Post source. This skeleton compiles against Business Central 29.0 symbols (checked 2026-11-17), but it has not been run. Insert subscribers against your target symbols (Shift+Alt+E) and compile during review.
In version 29, Sales-Post calls Commit() before OnAfterPostSalesDoc unless CommitIsSuppressed, InvtPickPutaway or PreviewMode is true. Microsoft documents that Commit() ends the current write transaction. Engineering note: do not assume a later subscriber error reverses an already committed posting.
Keep subscribers small
A subscriber should usually check applicability and delegate to a named codeunit. This makes the condition visible, allows direct tests of the business behavior, and prevents the event layer from becoming an unstructured collection of transaction logic.
Avoid user interface calls in subscribers that might run from APIs, job queues, or background sessions. Avoid synchronous external HTTP requests in posting flows. Do not add Commit() unless the publisher's contract explicitly requires and permits it; an unexpected commit can break transaction atomicity.
Make side effects idempotent
A subscriber can run again because a process is retried, an integration replays work, or another code path publishes the same business event. If it creates a queue entry, notification, or integration record, protect that side effect with a durable key or existence check. Build the key around the immutable SystemId and the specific operation; distinguish partial postings and company scope.
Treat skip flags as business choices
The final two booleans in EventSubscriber are SkipOnMissingLicense and SkipOnMissingPermission. They control what happens when the session lacks the subscriber codeunit's license or permission. Microsoft documents that true skips the subscriber call and continues with the next subscriber, while the default false raises an error instead. Do not set both to true merely to avoid deployment errors. Skipping a critical compliance or accounting rule could be worse than stopping the transaction.
Use IsHandled as a last resort
Some events expose an IsHandled parameter that lets a subscriber replace standard behavior. Microsoft's IsHandled guidance recommends limiting the pattern to a bare minimum. By convention only one subscriber handles the event, so each subscriber should exit first when IsHandled is already true, and nothing in the platform enforces that. Skipped base code can also stop other events from being raised, which breaks extensions that subscribe to them.
Prefer additive events, or OnSkip events that turn off as little code as possible. When replacement is necessary, document the bypassed behavior, test coexistence with installed apps, and fail clearly when assumptions are not met.
Test the event boundary
Test applicable and nonapplicable records.
Test preview, background, and web-service paths when the publisher supports them.
Test missing setup and permission behavior.
Test retry and idempotency for every created side effect.
Test interaction with other known extensions.
Run the suite against Business Central preview artifacts before release waves.
Handler and isolation techniques are covered in AL test automation with handlers and isolation.
Add telemetry around the delegated feature, not around every event call. Operations teams need to know whether the feature succeeded, failed, or was intentionally not applicable without collecting customer content. AL telemetry with Azure Application Insights covers how to emit those signals.
Turn the pattern into a scoped fix
For an inherited subscriber failure, collect the publisher, subscriber, expected behavior and one reproducible example for an AL development review. Keep credentials and customer data out of what you send.
Next step. If you are not sure which extensions and subscribers run in your environment, book the free BC Environment Snapshot: one hour on a screen share with a Business Central consultant, then a written summary of your environment within five business days. For new or failing extension work, see AL development services.
FAQ
Frequently asked questions
What is an event subscriber in Business Central?
A Business Central event subscriber is an AL method with the EventSubscriber attribute, declared inside a codeunit, that runs when a specific published event is raised. It lets an extension react to standard business logic, such as posting a sales document, without modifying Microsoft's base application. One event can have many subscribers, and the publisher does not know which subscribers exist.
How do I subscribe to a table event in AL?
Set ObjectType to ObjectType::Table and reference the table by name with Database::<TableName>, not Table::<TableName>, as Microsoft's EventSubscriber reference requires. For a field validate trigger event such as OnAfterValidateEvent, put the field name in the ElementName argument; other events leave it empty. Use Shift+Alt+E in the AL editor to insert a subscriber with the correct signature for your symbols.
What do SkipOnMissingLicense and SkipOnMissingPermission do?
They are the last two arguments of the EventSubscriber attribute. When set to true, Business Central skips the subscriber call if the session lacks the license or permission for the subscriber codeunit, and continues with the next subscriber. The default, false, raises an error instead, so set them deliberately: skipping an accounting or compliance rule can be worse than stopping the transaction.
Should I use IsHandled in Business Central event subscribers?
Only when no better event exists. Microsoft recommends limiting the IsHandled pattern to a bare minimum, because only one subscriber should handle the event by convention, and skipped code can stop other events from being raised. If you must use it, exit first when IsHandled is already true, document the bypassed behavior and test coexistence with other installed apps.
Does OnAfterPostSalesDoc run after the sales posting is committed?
In version 29, Sales-Post calls Commit() before OnAfterPostSalesDoc unless CommitIsSuppressed, InvtPickPutaway or PreviewMode is true. Microsoft documents that Commit() ends the current write transaction. As an engineering precaution, do not assume a later subscriber error reverses a posting that has already committed.
Sources
Claims in this article were checked against the following on Nov 18, 2026.
- learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/attributes/devenv-eventsubscriber-attribute
- learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-events-in-al
- learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/types-of-events-for-extensibility
- learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-use-ishandled-pattern
- learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-extensibility-overview
- learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/whatsnew/whatsnew-update-29-0
- github.com/microsoft/BCApps/blob/releases/29.0/src/Layers/W1/BaseApp/Sales/Posting/SalesPost.Codeunit.al
- bittaapps.com/services/al-development
- bittaapps.com/blog/business-central-environment-snapshot-one-hour
- learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/methods-auto/database/database-commit-method
- learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-table-system-fields
- learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-subscribing-to-events
- bittaapps.com/contact?intent=snapshot&source=blog_al_events
- bittaapps.com/contact?intent=snapshot&source=blog_al_events_end
- bittaapps.com/book-a-call
- bittaapps.com/blog/al-test-automation-handlers-isolation-upgrade-safe
- bittaapps.com/blog/al-telemetry-azure-application-insights-business-central