Saksflyt Saga Pattern

The saksflyt and saksflyt-api modules implement a saga pattern for orchestrating multi-step business processes asynchronously in melosys-api.

Quick Reference

Module Structure

saksflyt-api/    # Interfaces, domain classes, and service facade
├── ProsessinstansService.java   # Entry point for creating sagas
├── domain/
│   ├── Prosessinstans.kt        # Saga state entity
│   ├── ProsessType.java         # ~45 process type definitions
│   ├── ProsessSteg.java         # ~70 step definitions
│   ├── ProsessStatus.java       # KLAR, UNDER_BEHANDLING, PÅ_VENT, FERDIG, FEILET
│   ├── ProsessDataKey.java      # Data keys stored in saga
│   └── LåsReferanse*.kt         # Concurrency control

saksflyt/        # Execution engine and step implementations
├── ProsessinstansBehandler.java     # Main saga orchestrator
├── ProsessinstansOpprettetListener  # Event listener, starts sagas
├── ProsessinstansFerdigListener.kt  # Releases waiting sagas
├── ProsessinstansBehandlerDelegate.kt  # Locking logic
├── prosessflyt/
│   ├── ProsessFlyt.kt               # Flow definition (steps list)
│   └── ProsessflytDefinisjon.kt     # All flow mappings
└── steg/                            # Step implementations
    ├── StegBehandler.java           # Step interface
    ├── medl/                        # MEDL integration steps
    ├── sed/                         # SED/EESSI steps
    ├── brev/                        # Letter sending steps
    └── ...

Creating a New Saga

// In any service class, inject ProsessinstansService.
// Real signature (see ProsessinstansService.java) takes the full parameter list:
prosessinstansService.opprettProsessinstansIverksettVedtakEos(
    behandling, behandlingsresultatType, fritekst, fritekstSed,
    mottakerinstitusjoner, arbeidsgiverSkalHaKopi);

Step Implementation Pattern

@Component
public class MyStep implements StegBehandler {
    @Override
    public ProsessSteg inngangsSteg() {
        return ProsessSteg.MY_STEP;
    }

    @Override
    @Transactional(propagation = Propagation.REQUIRES_NEW)  // Each step has own transaction
    public void utfør(Prosessinstans prosessinstans) {
        // Access data: prosessinstans.getData(ProsessDataKey.SOME_KEY)
        // Access behandling: prosessinstans.getBehandling()
        // Do work...
    }
}

Key Concepts

Concept	Description
Prosessinstans	Saga state - tracks type, status, current step, data
ProsessType	Defines which saga to run (e.g., IVERKSETT_VEDTAK_EOS)
ProsessFlyt	Ordered list of steps for a process type
ProsessSteg	Individual step in a flow
StegBehandler	Step implementation (one per ProsessSteg)
låsReferanse	Concurrency lock key (e.g., RINA case ID)

Execution Flow

1. Create: ProsessinstansService creates Prosessinstans, publishes ProsessinstansOpprettetEvent
2. Queue Check: ProsessinstansOpprettetListener checks if saga should wait (låsReferanse) - BEFORE_COMMIT
3. Execute: ProsessinstansBehandler.behandleProsessinstansNå() runs steps in sequence - AFTER_COMMIT (dispatched via ProsessinstansDispatcher; ProsessinstansBehandlerDelegate.behandleProsessinstans() does the på-vent check and delegates here)
4. Complete/Fail: Status set to FERDIG or FEILET, ProsessinstansFerdigEvent published
5. Release: ProsessinstansFerdigListener starts next waiting saga with same lock group

Critical: The AFTER_COMMIT Misconception

Misconception: "Since the saga starts AFTER_COMMIT, it sees committed data."

Reality: AFTER_COMMIT guarantees DB commit, NOT fresh Java objects.

The saga receives the same Java object from the HTTP transaction. The behandling inside is a detached entity with potentially stale data. See stale-reference-problem.md.

Common Pitfalls

The sync/async split at transaction boundaries causes race conditions:

Issue	Symptom	Solution
Stale object reference	Silent corruption	Reload Prosessinstans in AFTER_COMMIT
Event listener + saga conflict	OptimisticLockingException	Move listener to saga step
Entity loaded across TX	Silent data corruption	Add @DynamicUpdate to entity
@Lob in equals/hashCode	Unstable Set membership	Use id-based equals

See Anti-Patterns and stale-reference-problem.md for details.

Detailed Documentation

• Architecture: Deep dive into component interactions
• Flow Definitions: All process types and their steps
• Concurrency Control: Locking mechanism, låsReferanse, and entity-level race conditions
• Anti-Patterns: Sync/async race conditions and how to avoid them
• Stale Reference Problem: AFTER_COMMIT misconception and investigation guide
• Common Patterns: Debugging, adding steps, error handling