Versioning Acumatica Business Events

A Business Event configured against a screen or GI is a live dependency on that screen or GI's exact field set. Nothing enforces that dependency at design time — an Acumatica version upgrade, a customization change, or someone renaming a GI field can silently break a trigger condition or a notification template, and the first sign is usually a business event that quietly stops firing.

Business Events are not part of a customization project by default

Unlike DAC extensions, graph extensions, and screens, Business Events are configuration data, not code — they're created and edited directly on the live instance through the Business Events screen. That means they don't automatically travel with a customization project the way compiled code does, and they're easy to lose track of during an environment refresh or a migration between instances unless someone deliberately includes them in the customization package or documents them separately.

What breaks across an Acumatica version upgrade

Field renames on standard DACs are rare but not unheard of across major version upgrades, and a Generic Inquiry built against a field that's renamed or removed will fail to run, taking its business events with it. More commonly, a version upgrade changes workflow stage names or adds required fields to standard screens, which can shift when a "row updated" condition actually fires relative to before. After any version upgrade, re-validate business events the same way you'd re-validate any other customization — run the trigger condition manually and confirm the subscriber still fires against a test record.

Versioning the queue and payload contract

For business events with a custom subscriber pushing data externally, the payload shape is a contract with whatever's on the receiving end — an Azure Function, a Lambda, a partner's webhook receiver. Treat changes to that payload the way you'd treat any API contract change: add fields without removing old ones where possible, and if a field genuinely needs to change shape, version the payload (an eventVersion field in the JSON) so the receiver can handle both old and new events during a transition instead of breaking the moment the Acumatica side deploys a change.

{
  "eventVersion": 2,
  "eventType": "ShipmentConfirmed",
  "refNbr": "SH00123456",
  "confirmedOn": "2026-07-05T10:15:00Z",
  "carrier": "DHL"
}

Documenting what a business event depends on

The least glamorous but most useful habit: keep a short written record, outside Acumatica, of every business event's source screen or GI, its trigger condition in plain language, and its subscriber(s) — including which external systems a custom subscriber talks to. Business Events configuration is invisible to a code diff and easy to forget exists until it breaks; a one-page list per instance turns "why did this stop working" from an investigation into a lookup.

Wrapping up

Business Events age the way any configuration-not-code integration ages — quietly, until an upgrade or a rename breaks a dependency nobody wrote down. Exporting them into the customization project and keeping a plain-language record of what each one depends on is most of the fix.