Acumatica TransactionScope — Usage and Pitfalls

I once inherited a customization where a developer, coming from a plain ADO.NET background, wrapped a chunk of custom persistence logic in a raw System.Transactions.TransactionScope around several PXCache.Persist calls, on top of Acumatica's own internal transaction handling. It worked in testing. Under real concurrent load it produced intermittent deadlocks that took two days to trace, because two separate transaction management systems were both trying to own the same connection's isolation semantics. TransactionScope in Acumatica is one of those tools that is genuinely necessary sometimes and actively dangerous most of the time.

PXGraph already wraps your Persist in a transaction, most of the time you don't need one

When you call Base.Save.Press() or a graph's Persist(), Acumatica already opens a database transaction covering every dirty row across every cache in that graph, runs RowPersisting for each, and commits or rolls back the whole batch atomically. This is the guarantee that makes "one exception anywhere rolls back the entire save" true. If your custom logic's data changes go through the graph's normal cache-and-persist flow, you already have transactional atomicity, adding an explicit TransactionScope around that flow does nothing except create a second transaction context wrapping the first, with its own isolation level and its own connection enlistment behavior that can conflict with what the graph is already doing.

The legitimate case: multiple independent graph instances that must succeed or fail together

TransactionScope earns its place when you are coordinating persistence across multiple separate PXGraph instances, each with its own independent transaction boundary, and the business requirement is that all of them commit together or none do. A classic example: a custom process that creates a Sales Order via one graph and a related Case via another graph, where a failure in the second must roll back the first, something Acumatica's own per-graph transaction handling cannot do for you since each graph instance normally commits independently.

using (var ts = new PX.Data.PXTransactionScope())
{
    SOOrderEntry orderGraph = PXGraph.CreateInstance<SOOrderEntry>();
    // ... build and persist the order via orderGraph.Save.Press() ...

    CRCaseMaint caseGraph = PXGraph.CreateInstance<CRCaseMaint>();
    // ... build and persist the related case via caseGraph.Save.Press() ...

    ts.Complete(); // both graphs' work commits together, or neither does
}

Note the type: Acumatica ships its own PX.Data.PXTransactionScope, specifically built to coordinate correctly with PXGraph's internal connection and transaction handling, rather than the raw System.Transactions.TransactionScope. Using the platform's own wrapper is what avoids the MSDTC promotion and deadlock issues that show up when a bare framework TransactionScope tries to manage a connection Acumatica's data layer is also managing.

Nesting scopes correctly, and why nested Persist calls surprise people

A PXTransactionScope can legitimately nest, an outer scope wrapping several graphs, each doing its own internal Persist, and the outer scope determines the actual commit point. What surprises developers moving from a simpler ORM is that a graph's own internal Persist call, inside an active outer scope, does not commit immediately, it enlists in the ambient scope and only actually commits when the outermost scope calls Complete() and disposes cleanly. If an exception is thrown anywhere after a graph's Persist has run but before the outer scope completes, that graph's changes roll back too, even though the Persist call itself appeared to succeed without throwing. Code that assumes "Persist succeeded, so that data is now safely committed" inside a multi-graph TransactionScope is making a false assumption that eventually produces a very confusing partial-state bug report.

Isolation level defaults matter more than people check

PXTransactionScope's default isolation level is tuned to work correctly with how Acumatica's own data layer expects to read and lock rows; overriding it to something looser or stricter without understanding why the default was chosen is how deadlocks and phantom-read bugs get introduced by well-meaning developers trying to "fix" an unrelated performance complaint. If a specific operation genuinely needs a different isolation level, that decision deserves a code comment explaining why, because the next developer reading it will otherwise assume it was an accident.

Wrapping up

Most Acumatica customizations never need an explicit TransactionScope at all, because PXGraph's own Persist already provides atomicity across every cache in that graph. Reach for PX.Data.PXTransactionScope, not the raw framework type, only when coordinating commits across genuinely separate graph instances, keep the scope as narrow as possible, never let it span an external network call, and remember that a Persist call inside an active outer scope has not actually committed until that outer scope completes. The deadlocks and partial-state bugs I have debugged in this area have, without exception, come from ignoring one of those rules.