Migrating Camunda 7 Process to Camunda 8

Camunda is a powerful platform for process and decision automation and migrating from Camunda 7 to Camunda 8 presents unique challenges. This blog post is designed to equip you with the knowledge and tools to plan and execute this transition strategically. We explain the key differences between Camunda 7 and 8, why a migration is worthwhile, and how the migration can succeed using a simple example. This migration guide is designed to help navigate the complexities and make informed decisions on the path of a first migration. The migration of current Camunda 7 instances, i.e. process instances and database, is not covered in this blog post.

We will use our BPM exercise from GitHub for some practical examples. In Chapter 2 on the ‘possible-solution’ branch is a Camunda 7.20 Spring Boot application with a BPMN process, DMN table, and several Java Delegates: NovatecConsulting/bpm-exercise: First Steps with BPMN2.0 and Camunda7. We will migrate to Camunda 8.6.

Understand the Key Differences

Camunda 7 and Camunda 8 differ in some key aspects. However, we will not look at these comprehensively here, as this blog post is about the practical migration steps:

• Architecture: Camunda 8 is built on a cloud-native architecture, which means it is designed for scalability and resilience. Camunda 7 is primarily designed for on-premise deployments, which may require significant infrastructure management.
• Job Workers vs. Java Delegates: In Camunda 7, you often used Java Delegates or Job Workers (in the form of External Tasks) for executing business logic within your BPMN processes. In Camunda 8, you will typically use Job Workers or Connectors instead.

Camunda 7: Service Tasks and Java Delegates:

• Execution Model: In Camunda 7, when a BPMN process reaches a Service Task, it executes the associated Java Delegate or external task directly within the process engine. This means that the business logic was tightly coupled with the process execution.
• Deployment: Java Delegates were typically packaged as part of the application that contained the BPMN processes. This meant that any changes to business logic required redeploying the entire application.

@Component
public class StudentDelegate implements JavaDelegate {
    StudentInputPort studentInputPort;
    public StudentDelegate(StudentInputPort StudentInputPort) {
        this.studentInputPort = StudentInputPort;
    }
 
    @Override
    public void execute(DelegateExecution execution) {
        // Retrieve process variables from Camunda execution
        String email = (String) execution.getVariable("email");
 
        // Execute the use case
        boolean studentExists = studentInputPort.checkIfStudentExists(email);
 
        // Set process variable based on the result
        execution.setVariable("studentExists", studentExists);
    }
}

Camunda 8: Job Worker

In contrast, Camunda 8 introduces a more flexible and decoupled approach with dedicated Job Workers:

• Execution Model: In Camunda 8, Job Workers are external components that can be implemented in any programming language (e.g., Java, Node.js, Python). They listen for jobs from the process engine and execute them independently. This decouples business logic from process execution, allowing for greater flexibility and scalability.
• Communication: The communication model has shifted to an asynchronous pattern. When a BPMN process reaches a task:
  • The process engine creates a job and places it in a queue.
  • Job Workers poll this queue for available jobs.
  • Once a Job Worker picks up a job, it executes it independently of the process engine.
  • The engine does not block while waiting for job completion; it continues processing other tasks or jobs.
• Scalability: Multiple instances of Job Workers can be deployed independently to handle tasks concurrently. This allows organizations to scale their processing capabilities based on demand without affecting the core process engine.
• Deployment Flexibility: Since Job Workers are separate from the BPMN processes themselves, they can be developed, deployed, and scaled independently. This means you can update your business logic without redeploying your entire workflow application.

So, remember that there is no support for Java Delegates in Camunda 8 anymore. Instead, the code is typically executed by job workers or connectors.

Connectors

Camunda 7: Connectors were available but often required custom implementation or third-party libraries to integrate with external systems.

Camunda 8: Connectors are more robust and user-friendly. They provide pre-built integrations with various services (like REST APIs, databases, etc.) out-of-the-box. This allows developers to easily connect their workflows to external systems without writing extensive code. Some information on out-of-the-box connectors: Overview | Camunda 8 Docs and an example connector: AWS S3 Connector | Camunda Marketplace.

Summary

Category	Camunda 7	Camunda 8
Execution Model ‘for Services’	Synchronous execution via Java Delegates	Asynchronous execution via Job Workers
Communication between Engine and Service	Directly tied to process execution	Decoupled; uses a polling mechanism
Scalability	Limited by application deployment	Horizontally scalable with deployments of  independent workers
Deployment ‘of Services’	Requires redeployment of entire app	Independent deployment of workers

For further reading please see: Conceptual differences with Camunda 7 and Camunda 8 | Camunda 8 Docs.

Why Migrate to Camunda 8?

Before we look at the migration steps, let’s briefly mention why a migration might be worthwhile:

• Cloud-Native Architecture: Camunda 8 is designed for cloud environments, offering better scalability and resilience. Therefore obviously fitting well into the cloud strategies of your company.
• Enhanced Performance: Camunda 8 leverages a new engine, called Zeebe, that improves performance and reduces latency (see further reading: Scaling Workflow Engines at Intuit with Camunda 8 and Zeebe | Camunda).
• Improved User Experience: The new Tasklist and Cockpit, in Camunda 8 now called Operate, provide a more intuitive interface. Camunda 8 also offers functions for collaboration in the creation of BPMN/DMN models, which facilitates process design.
• Message buffering: Camunda 8 enables the buffering of messages, which reduces the complexity of process models and improves data consistency.
• User-friendly scripting language (FEEL): FEEL is easy to understand for business users and supports JSON data structures, reducing the need for technical expertise.
• Out-of-the-box connectors: The use of ready-made or user-defined connectors improves the automation and orchestration of processes without extensive programming knowledge.

Topics

In the following, we will discuss different technical parts of Camunda 7 independently, so that you can read each topic on its own if you are only interested in certain migration topics.

As mentioned before we will use our bpm-exercise from GitHub for some practical examples. In Chapter 2 on the ‘possible-solution’ branch is a Camunda 7.20 Spring Boot application with a BPMN process, DMN table, and several Java Delegates: NovatecConsulting/bpm-exercise: First Steps with BPMN2.0 and Camunda7. We will migrate to Camunda 8.6.

Your current Situation and Environment

Assess Your Current Setup

Before starting the migration, assess your current Camunda 7 setup. Identify the following:

• Processes: List all BPMN processes you have deployed.
• Decision Models: Identify DMN decision tables in use.
• Custom Code: Review any custom Java code or external services integrated with your workflows (refactoring Java Delegates to Job Workers will be covered in a follow-up blog post).
• Note that an update of your project will be necessary (remove the embedded engine and add the Zeebe client). Pay attention to the change from Camunda 7 APIs to Zeebe APIs or Zeebe client (this topic is not in the scope of this blog post).

Analyze Your Existing Processes

Start by analyzing your existing BPMN processes in Camunda 7. Identify all components that need to be migrated:

• Java Delegates: These are custom Java classes that implement business logic.
• Service Tasks: These tasks call external services or perform specific actions.
• User Tasks: These remain largely unchanged but may require adjustments in user interfaces.

Note that some activities and tools that were available in Camunda 7, may no longer exist in Camunda 8. These may or may not be added in later Camunda 8 versions. You can find an overview of all Camunda 8 releases here.

SaaS vs Self-Managed

You can either set up your own cloud environment and deploy Camunda 8 yourself (Self-Managed) or rent a cluster from Camunda themselves and run it as a Software as a Service (SaaS) solution. Although both options are part of the same application, there are key features and differences to consider when choosing the right path. The decision will depend on factors like regulations, time, and budget constraints. Covering these differences in detail is beyond this article’s scope, so for our example, we will focus on using Camunda 8 SaaS.

Practical meaning for our application

In our Camunda 7 application from chapter 2 from our GitHub repository (NovatecConsulting/bpm-exercise: First Steps with BPMN2.0 and Camunda7) we found:

• One BPMN process in main/resources: exam-registration.bpmn
• One DMN table in main/resources: examRegistrationPeriod.dmn
• One Execution listener in main/java/adapters/camunda: StartExectionListener.java
• Several Java Delegates in main/java/adapters/camunda

For our environment, we are using a Camunda 8 SaaS instance.

We will use the open source converter for our simple example to achieve a quick migration. We converted our Camunda 7 BPMN process to a Camunda 8 BPMN process using the Webapp.

The process looks completely the same. What changed:

• All JUEL expressions in the sequence flows were converted to FEEL.
• All delegate calls in the service and send tasks using ‘${exampleDelegate}’ were transformed from ‘delegateExpression’ to job types using  ‘camunda-7-adapter’.
• The element ‘fromData’ in the user tasks couldn’t be transformed. Further manual adjustments are needed.

A report is automatically generated with a conversion listing all items that have been changed or transformed.

In addition, manual versioning of processes is no longer supported (see here).

BPMN Elements

Update User Tasks

User Tasks generally remain similar between versions but may require updates based on user interface (UI) changes or new features in Camunda 8. Review any forms associated with User Tasks and ensure that any frontend applications interacting with these tasks are updated accordingly.

Timer Events

Timer intermediate events are supported but may require adjustments based on how timeouts are managed in the new version.

Gateways

Almost nothing changes: Exclusive, Parallel,  and Event-Based Gateways are fully supported in Camunda 8 and continue to function as expected. Complex Gateways are not included in Camunda 8 yet.

Messaging Events

In Camunda 8, Message Events have been enhanced for better integration with external systems. Ensure that your message correlation logic is updated according to the new event-handling mechanisms. The subscription of messages: Messages are not sent directly to process instances. Instead, the correlation is based on subscriptions that contain the message name and the ‘correlationKey‘.

Architecture

Camunda 7: Uses a monolithic architecture in which messaging is managed directly via the process engine.

Camunda 8: Here, messaging is often handled via external systems or event streaming platforms (such as Kafka).

Event handling

Camunda 7: Messages are processed directly within the process instance, which means that the logic for receiving and processing messages is implemented in the engine itself.

Camunda 8: Provides improved event handling that allows messages to be processed asynchronously. This means that processes can react better to external events without having to be constantly active.

Practical meaning for our application

Let’s view our converted process, now being a Camunda 8 BPMN.

There are two User Tasks. In Camunda 7 there were of type ‘Generated Task Forms‘ where all the form fields were defined in the process model in the properties of the User Task. This is no longer possible with Camunda 8. For Camunda 8 we can choose between the types ‘Camunda Form‘ and ‘External form reference‘. Because we are using a Camunda 8 SaaS instance we will use ‘Camunda Form‘, give the process a Form ID, and create a form in the Camunda Modeler.

The Timer Boundary Event stays the same. Type ‘Duration‘ with value ‘P7D‘ works in Camunda 7 and 8 the same.

The same applies to the Gateways. Only the expressions in the sequence flows need to be adjusted from JUEL to FEEL. This was done automatically by our Camunda-7-to-camunda-8-converter. We only check if the FEEL expressions make sense. The conversion results are easy to understand e.g.:

• Condition expression: Please review transformed expression: ‘${studentExists}‘ -> ‘=studentExists‘.
• Condition expression: Please review transformed expression: ‘${!studentExists}‘ -> ‘=not(studentExists)‘.

There are three Message Tasks in our process, all Send Tasks. The converter did the following:

• Attribute ‘delegateExpression‘ on ‘sendTask‘ was mapped. Delegate call to ‘${emailDelegate}‘ was transformed to job type ‘camunda-7-adapter‘. Please review your implementation.

The migration that we perform from chapter 2 of the GitHub repo will be provided in chapter 3. There you can take a look at the code yourself if you like.

Camunda 7 Adapter

In this chapter, we now turn to the implementation of this so-called ‘camunda-7 adapter‘, which can be used by Spring Boot applications: camunda-7-to-8-migration/camunda-7-adapter at main · camunda-community-hub/camunda-7-to-8-migration. This open-source project allows us to reuse existing Java Delegates by collecting them all and exposing them under a single worker topic ‘camunda-7-adapter‘. This adapter is not meant to cover all possible situations, but it might work out of the box in some cases. The following steps will guide you through the process of implementing this framework.

1. First, we need to add the Camunda adapter as a dependency.

Gradle:

Implementation( “org.camunda.community.migration:camunda-7-adapter:${version}”)

Maven:

<dependency>
    <groupId>org.camunda.community.migration</groupId>
    <artifactId>camunda-7-adapter</artifactId>
    <version>${version}</version>
</dependency>

The latest version can be found here. Replace Camunda 7 dependencies with Camunda 8. Start by adding the Camunda 8 SDK.

Gradle:

Implementation( “io.camunda:spring-boot-starter-camunda-sdk:${sdkVersion}” )

Maven:

<dependency>
    <groupId>io.camunda</groupId>
    <artifactId> spring-boot-starter-camunda-sdk </artifactId>
    <version>${sdkVersion}</version>
</dependency>

Note that not every SDK version is compatible with the Camunda 7 adapter. At the time of writing the latest SDK version compatible with the latest adapter version is sdkVersion = 8.6.5 with adapterVersion = 0.10.1. Now remove the remaining Camunda 7 dependencies.

3. If you had a Jasper config or any other component that exposed the engine to the outside world, delete it. These components are not needed anymore.

4. Add the ‘@EnableCamunda7Adapter‘ annotation to your main class.

5. If you leveraged automatic deployments of classpath resources, add the ‘@Deployment‘ annotation and list all resources you want to see deployed. Wildcards are also supported:

Java:

Import io.camunda.zeebe.spring.client.annotation.Deployment;
 
@SpringBootApplication
@EnableCamunda7Adapter
@Deployment( resources = { “classpath:/path/to/converted-c8-exam-registration.bpmn” , “classpath:/business/decisions/*.dmn“ } )
public class Application {
    public static void main(String... args) {
        SpringApplication.run(Application.class, args);
    }
}

This configuration for example deploys a single BPMN file named ‘converted-c8-exam-registration.bpmn‘ and all DMNs found in ‘/business/decision‘.

6. Finally, we can now focus our attention on the BPMN diagram itself. To transform a previous delegate expression into a Camunda 8 compatible worker simply set ‘camunda-7-adapter‘ as its job type and add a custom header with ‘delegateExpression’ as its key and ‘${delegateName}’ as its value (as mentioned above in the previous chapter). In a way, the definition ‘just moved’ into a header value rather than the job definition itself. And done. You should now be able to execute your BPMN using the existing Spring Boot application and a Camunda 8 Cluster.

Migrating to Camunda 8 using the Camunda-7-Adapter offers several benefits: it’s quick, easy to use, and doesn’t require explicit worker knowledge. However, it comes with limitations, such as being confined to the Camunda 7 delegate API and requiring compatibility with the Camunda 8 SDK version.

DMN

Migrate Decision Tables

The migration from DMN is essentially just switching from JUEL to FEEL. The configuration settings of modeler:executionPlatform and modeler:executionPlatformVersion in the XML are automatically updated when you upload a DMN file to Camunda 8 Modeler: Adjust DMN models | Camunda 8 Docs.

Practical meaning for our application

We didn’t need to adjust anything in the DMN. We therefore uploaded the DMN as it is into our Camunda 8 SaaS:

Camunda Forms

When migrating from Camunda 7 to Camunda 8, the handling of forms undergoes some changes. Here’s a breakdown of what happens with Camunda Forms during the migration:

Form Types

In Camunda 7, there are several ways to define forms for User Tasks:

• Embedded Forms: HTML forms defined directly in the BPMN model.
• External Forms: Forms hosted outside of the Camunda engine, often using web applications.
• Camunda Forms: A specific type of form that uses the Camunda Form Builder.

In Camunda 8, while you can still use external forms, the concept of Camunda forms has changed, and embedded forms are no longer useable. The focus is more on integrating with modern front-end frameworks and applications.

Embedded (HTML) Forms

If you used embedded forms in Camunda 7, you will need to migrate these to a new format in Camunda 8:

Recreate Embedded Forms:

• You will need to recreate any embedded forms e.g. using a compatible front-end technology (like React, Angular, or Vue.js) since Camunda 8 encourages a more flexible approach to UI development.
• Change the corresponding User Tasks in your BPMN model to reference the new external forms. In Camunda 8, you can do this by setting the attribute Form Key to the URL of the external form.

Conversion of the forms to Camunda Forms:

• Remodel the forms in the Camunda 8 (Web) Modeler.
• This option offers the possibility of being able to create further forms in the future without further implementation effort.
• Assign the Camunda forms to the corresponding User Task.

Using External Forms

For external forms that were already implemented in Camunda 7:

• No Major Changes Required: If your external forms are functioning correctly and are accessible via URLs, they can continue to be used in Camunda 8 without significant changes. Just ensure that the integration points remain valid.

Data Binding and Variables

When migrating forms, pay attention to how data binding and variable handling work:

• Ensure that any variables used in your forms are correctly mapped to process variables in your BPMN models.
• Review how user input is captured and sent back to the process engine.

Conclusion

In summary, when migrating from Camunda 7 to Camunda 8, you will need to adapt your approach to forms significantly. While external forms can often be reused with minimal changes, embedded forms must be recreated using modern web technologies or the Camunda 8 Modeler. 

Practical meaning for our application

In our application, we converted our Camunda forms in chapter ‘BPMN Elements’, which means we have recreated the forms in the Camunda 8 Modeler.

Conclusion

Migrating from Camunda 7 to Camunda 8 involves careful planning and execution of several steps, including transitioning from Java Delegates to Job Workers and utilizing Connectors for service interactions. In our example, we have shown the use of the camunda-7-adapter in a kind of ‘first migration’. In the next step, we will look at refactoring Java Delegates to Job Workers. This will be covered in a follow-up blog post.

If you have any questions or need assistance during your migration journey, feel free to reach out!

Resources

Public GitHub repository (Novatec): NovatecConsulting/bpm exercise: First steps with BPMN2.0 and Camunda7