The Acumatica Framework provides a robust event model that allows developers to inject business logic at specific points during data manipulation. Understanding these events and their execution order is essential for building reliable customizations and extensions.

Event Handler Types

The Acumatica Framework provides two types of graph event handlers: classic and generic. [citation:1] Both work the same way, but generic handlers are recommended for modern development. [citation:1]

Code Examples

Classic Handler:

protected virtual void CROpportunityProducts_RowSelected(
    PXCache sender, PXRowSelectedEventArgs e)
{
    // Business logic here
}

Generic Handler (Recommended):

protected virtual void _(Events.RowSelected<CROpportunityProducts> e)
{
    // Business logic here
}

Field-Level Generic Handler:

protected virtual void _(Events.FieldUpdated<CROpportunityProducts.contactID> e)
{
    // Business logic here
}

The PXCache and Data Events

All data-related events in Acumatica are raised by PXCache objects. The cache manages modified data records and provides the controller for basic operations like Insert(), Update(), Delete(), and Persist(). [citation:12]

Each cache object contains:

• Modified Records: Data that has been Inserted, Updated, or Deleted but not yet saved
• Controller: Methods that execute data operations and raise events

Event Execution Sequence

Events in Acumatica are raised in a specific, well-defined order. Understanding this sequence is critical for writing reliable business logic. [citation:2][citation:5]

Update of a Data Record

When a data record is updated, the following sequence occurs: [citation:2]

1. Field Events - For each updated field in sequence:
   • FieldUpdating - Before the field value is changed
   • FieldVerifying - To validate the new value
   • FieldUpdated - After the field value is changed
2. RowUpdating - Before the record is updated in the cache. At this point, e.Row holds the old version and e.NewRow holds the updated version.
3. Actual Update - The data record is copied to the PXCache
4. RowSelected - Only the updated record can be accessed through e.Row
5. RowUpdated - After the update completes. e.Row holds the updated instance, while e.OldRow holds the previous version. [citation:2]

Insertion of a Data Record

When inserting a new record: [citation:6]

1. Field Events - For each field (including FieldDefaulting for default values)
2. RowInserting - Before the record is inserted into the cache
3. Actual Insert - The record is added to PXCache
4. RowInserted - After the insertion completes

Graph vs. Attribute Event Handlers

Events in Acumatica can be handled in two different contexts: [citation:3]

Attribute Event Handler Example:

public class MyAttribute : PXEventSubscriberAttribute,
                           IPXFieldVerifyingSubscriber,
                           IPXRowPersistingSubscriber
{
    public virtual void FieldVerifying(PXCache sender,
                                       PXFieldVerifyingEventArgs e)
    {
        // Validation logic applied to all fields with this attribute
    }

    public virtual void RowPersisting(PXCache sender,
                                      PXRowPersistingEventArgs e)
    {
        // Pre-save logic applied to all DACs with this attribute
    }
}

Execution Order of Event Handlers

The order in which event handlers execute depends on the event type and how they're declared. [citation:8]

Bubbling Strategy (Bottom-Up)

Events added to the end of the collection execute from the base event handler up to the highest extension level. [citation:8]

• FieldUpdated
• RowSelecting
• RowSelected
• RowInserted
• RowUpdated
• RowDeleted
• RowPersisted

Tunneling Strategy (Top-Down)

Events added to the beginning of the collection execute from the highest extension level down to the base handler. [citation:8]

• FieldSelecting
• FieldDefaulting
• FieldUpdating
• FieldVerifying
• RowInserting
• RowUpdating
• RowDeleting
• RowPersisting

Event Handlers with Additional Parameter

When using the PXOverride pattern with event handlers, you can control execution order explicitly. The delegate pattern allows you to decide whether to invoke the base handler: [citation:8]

protected virtual void FieldVerifying(PXCache sender,
                                       PXFieldVerifyingEventArgs e,
                                       PXFieldVerifying del)
{
    // Custom validation first
    if (e.NewValue == null)
        throw new PXException("Value cannot be null");

    // Invoke the base handler or skip it
    del(sender, e);
}

Controlling Field Event Sequence

Field events are triggered in the order fields are declared in the DAC. This can be controlled using the TabOrder property of the PXUIField attribute. [citation:7]

#region DocType
[PXDBString(3, IsKey = true, IsFixed = true)]
[ARInvoiceType.List()]
[PXUIField(DisplayName = "Type", TabOrder = 0)]
public override String DocType { get; set; }
#endregion

Workflow Events

Acumatica also supports workflow events for cross-graph interactions. These are similar to .NET events and can trigger transitions between workflow states. [citation:11]

Key components of workflow events:

• Event Declaration: Define events in a nested class within the DAC using PXEntityEvent
• Event Handler: Declare a PXWorkflowEventHandler member in the graph
• Event Binding: Bind handlers to events in the screen configuration
• Firing Events: Call FireOn() on the event instance

// Event declaration
public partial class SOOrderShipment : IBqlTable
{
    public class Events : PXEntityEvent<SOOrderShipment>.Container<Events>
    {
        public PXEntityEvent<SOOrderShipment, SOInvoice> InvoiceLinked;
    }
}

// Firing the event
SOOrderShipment.Events
    .Select(e => e.InvoiceLinked)
    .FireOn(graph, self, invoice);

Best Practices

Common Pitfalls to Avoid

Conclusion