Orchestration Saga

Axon Framework has first-class support for exactly this pattern. A class annotated @Saga represents a single running instance of an orchestrator — one object per in-flight process, created automatically when a matching starting event arrives and destroyed automatically once the process ends.

Three annotations do the real work:

• @StartSaga marks the event handler that creates a new saga instance. When this event is published, Axon instantiates a fresh @Saga object to track this one specific process.
• @SagaEventHandler marks every other event handler the saga reacts to while it's alive, each one usually issuing the next command in the sequence.
• @EndSaga marks the handler whose event signals the process is finished, telling Axon it's safe to discard this saga instance.

Every @SagaEventHandler (including the one marked @StartSaga) needs an associationProperty — the name of a field Axon should match against the incoming event to figure out which saga instance the event belongs to.

This is meaningfully different from choreography's plain @EventHandler. A saga instance carries its own state (like a loan ID and account ID) across multiple events over time, whereas a stateless @EventHandler reacts to one event with no memory of what came before.

Here is the same loan approval process from before — approve a loan, deposit funds, update a credit profile — implemented as an explicit orchestrator instead of three independent listeners.

Reading this class top to bottom tells you the entire story of the process: it starts on LoanApprovedEvent, sends DepositFundsCommand; reacts to FundsDepositedEvent, sends UpdateCreditProfileCommand; and ends on CreditProfileUpdatedEvent. That's a genuine, tangible payoff of orchestration — the multi-step plan is visible in one place, instead of being spread implicitly across three separate listener classes in three separate services.

Notice what the participating services look like from this saga's point of view: Accounts Service just needs to know how to handle DepositFundsCommand and publish FundsDepositedEvent when it's done. It has no idea it's part of a saga at all — it's just responding to a command like it would respond to any other command. All of the sequencing awareness lives in LoanApprovalSaga, not in the services it coordinates. This is the coupling trade mentioned earlier: the orchestrator now explicitly depends on knowing about Accounts Service, Customer Service, and the commands each one accepts — but in exchange, those services themselves stay simple and saga-agnostic.

The saga's own fields — loanId and accountId — persist between event handler calls for the lifetime of this one saga instance. Axon manages that persistence automatically; you don't need to manually save or load saga state anywhere in this code.

@Saga
public class LoanApprovalSaga {

    @Autowired
    private transient CommandGateway commandGateway;

    private String loanId;
    private String accountId;

    @StartSaga
    @SagaEventHandler(associationProperty = "loanId")
    public void on(LoanApprovedEvent event) {
        this.loanId = event.getLoanId();
        this.accountId = event.getAccountId();
        commandGateway.send(new DepositFundsCommand(event.getAccountId(), event.getLoanAmount()));
    }

    @SagaEventHandler(associationProperty = "accountId")
    public void on(FundsDepositedEvent event) {
        commandGateway.send(new UpdateCreditProfileCommand(event.getCustomerId(), loanId));
    }

    @EndSaga
    @SagaEventHandler(associationProperty = "loanId")
    public void on(CreditProfileUpdatedEvent event) {
        // Saga finished successfully — Axon automatically ends and cleans it up here.
    }
}

Compensation in orchestration looks structurally similar to choreography's — a command gets sent to undo an earlier step — but who makes that decision is different, and that difference matters.

In choreography, Loans Service itself had to know to listen for DepositFailedEvent and decide, on its own, to send CancelLoanCommand. In orchestration, the saga is the one listening for the failure and the one deciding to compensate. Loans Service doesn't need any awareness that a saga exists at all — it just needs to know how to handle CancelLoanCommand whenever it arrives, the same as any other command.

SagaLifecycle.end() explicitly tells Axon this saga instance is finished — no further steps are expected, and Axon can safely discard its state. This is worth contrasting with the @EndSaga annotation used on the happy path: @EndSaga ends the saga automatically as a side effect of handling a specific event, while SagaLifecycle.end() ends it imperatively, from inside a handler that might also be doing other things, like sending a compensating command first.

The practical benefit shows up when a process has more than one possible failure point. With orchestration, every failure path — and every corresponding compensation — is a handler inside the same class, next to the happy path it's compensating for. Reading the saga tells you not just what should happen, but everything that could go wrong and exactly how each failure gets handled. That's much harder to get a complete picture of in choreography, where each service only knows about the one failure event it personally listens for.

@SagaEventHandler(associationProperty = "accountId")
public void on(DepositFailedEvent event) {
    commandGateway.send(new CancelLoanCommand(loanId)); // The saga decides to compensate, explicitly.
    SagaLifecycle.end(); // And explicitly ends itself here — no further steps expected.
}

Neither pattern is strictly better — they make different trade-offs, and the right choice depends mostly on how many steps are involved and how much explicit visibility into failure handling actually matters.

	Choreography	Orchestration
Where the plan lives	Implicitly, spread across many independent listeners	Explicitly, in one saga class
Coupling	Looser — services only know about event types, not each other	The orchestrator knows about every participant; participants stay simple
Best fit	A small number of steps, loosely related services	Longer or more complex flows, or ones needing a clear audit trail
Failure handling visibility	Scattered — each service only sees its own compensation	Centralized — every failure path lives in one class

A practical rule that holds up well in real systems: start with choreography for a short, loosely coupled flow, and deliberately migrate to orchestration once step count grows past four or five, once compensation logic starts getting complicated, or once someone genuinely needs to answer "what exactly happens during this process, end to end" without spelunking through several codebases.