Migrating from Camunda 7 to 8 with Clean Architecture

June 5, 2026•1,056 words

Introduction: Addressing the Migration Challenge

If your Camunda 7 codebase looks like the following, migrating to Camunda 8 will feel like a nightmare.. Framework calls are spread across controllers, services, and even repositories, meaning you’ll have to touch every layer during migration. A time-consuming, error-prone, and stressful process.

Framework usage spread across all layers: a migration nightmare

The root cause is tight coupling between your business logic and the process engine. Camunda 7’s embedded engine allowed direct Java method calls, but Camunda 8’s Zeebe engine runs as a remote service, communicating only via message passing and external tasks (job workers). This architectural shift breaks any code that directly depends on the engine. Teams often discover too late that their architecture is not prepared for this transition.

This article demonstrates how Clean Architecture and tactical Domain-Driven Design (DDD), as domain centric architecture approach, can isolate your domain from the process engine, turning migration into a localized, manageable change rather than a system-wide rewrite. It is based on my talk Leverage Clean Architecture for Easy C8 Migration.

Note: This approach is recognized in the Camunda Community Migration Guide as a recommended pattern for minimizing invasive changes.

The Core Problem: Tight Coupling with the Process Engine

In many Camunda 7 projects, interactions with the process engine are scattered across all layers of a classical multi-layer architecture. You might find:

A bit of RuntimeService in the controller
Some TaskService or HistoryService calls in the service layer
Even process variable checks or updates in the repository layer

This scattered usage creates a migration nightmare. Imagine standing in front of a chaotic, unsorted fruit stand, where apples, oranges, and bananas are all mixed together. Now, try to pick out only the apples, without disturbing the rest. That’s what migrating tightly coupled Camunda 7 code feels like. It’s stressful, time-consuming, and error-prone.

But migration should not mean throwing away your old codebase and starting from scratch. Instead, it should mean:

Keeping your business-representative code stable
Ensuring your domain objects and rules remain independent of the framework
Making local, isolated changes in predefined, specific locations

The Additional Challenge: Distributed Transactions

Camunda 8 doesn’t just introduce a new (remote) engine, it also brings distributed transactions. In this new architecture, the process state and your business logic no longer share the same runtime. This separation can lead to consistency challenges, such as when a process step fails after the business logic has already committed.

While we won’t dive deep into distributed systems theory here, it’s important to recognize that this adds another layer of complexity to the migration. For a thorough exploration of this topic, I recommend Leveling up! Mastering the distributed transaction challenge in zeebe.

Let your architecture support you on your migration journey

What you want are local, isolated changes in predefined locations, not changes spread all over the place. This is why I recommend domain-centric architecture approaches like Clean Architecture combined with Domain-Driven Design (DDD).

The heart of your architecture is the domain core—where your business entities and use cases live. This core is protected by layers of adapters, ensuring that changes to the process engine (like migrating from Camunda 7 to 8) only affect the outermost layer.

In Clean Architecture, the domain core, containing your entities and use cases, is only accessed by the surrounding layers. The outer circles represent "mechanisms" supporting your domain center. The dependency rule is clear: dependencies must always point inward. To achieve this, the domain code must not have any dependencies pointing outward. Instead, all dependencies point toward the domain code.

Without Mapping the effort is useless

Without mapping between layers, you miss the biggest advantage of Clean Architecture: decoupling your domain core from the outer (infrastructure) layers. If you do not map between your inner and outer layers, you are not isolated. When a third-party system changes its data model, as happens with the Camunda 7 to 8 migration, your domain core would need to change as well, defeating the purpose of Clean Architecture.

BPMN as a First-Class Citizen

Besides treating the process engine like an infrastructure adapter, you need to keep in mind that your process models, your BPMN diagrams, are part of your domain core. They represent business logic.

Why BPMN Belongs in the Domain Core

While BPMN files may contain Camunda-specific attributes, the process logic itself is framework-agnostic. The BPMN standard ensures that:

The flow (e.g., sequences, gateways) can be understood by any compliant tool
The business rules (e.g., "A flight must be booked before a hotel") remain in your domain layer

Practical Implications

Treat your BPMN diagrams like your domain entities:

Version them alongside your code
Test them as part of your domain logic

For example, you could add a process module to your existing domain module resulting in something like this for a maven multi-module project, e.g.:

domain/
├── model/
│   └── src/
├── process-model/  # BPMN diagrams as part of the domain
│   └── src/
└── service/
    └── src/

Conclusion

Migrating from Camunda 7 to 8 doesn’t have to be a high-risk, all-or-nothing endeavor. By applying Clean Architecture and Domain-Driven Design principles, you can isolate your domain logic from the process engine, making migration a localized, manageable change.

The key insights are:

Keep your domain framework-agnostic
Treat BPMN as a first-class citizen in your architecture
Use ports and adapters to isolate process engine dependencies
Map between layers to maintain decoupling

This approach not only eases migration but also results in more maintainable, flexible, and business-focused process applications.

However, keep in mind that the migration approach shown here only covers your codebase. You may also need to migrate your process models, runtime data, and prepare your infrastructure team for Camunda 8 (if not using SaaS). For the first two concerns you may want to have a look at the Camunda Migration Tools, which even provide an open rewrite recipe for your Java Delegates.