Migration tooling
Camunda currently invests in tooling to help support and ease your migration from Camunda 7 to Camunda 8.
The migration tooling is currently under development, with an initial release planned for Camunda 8.8 (October 2025).
Migration tools
Camunda provides the following migration tools:
| Migration tool | Description |
|---|---|
| Migration Analyzer | Gain a first understanding of migration tasks. Available for local installation (Java or Docker) or hosted as a free SaaS offering. |
| Data Migrator | Copies active Camunda 7 runtime instances and existing audit trail data (history) to Camunda 8. |
| Code Converter | Supported by a mixture of diagram conversion tools, code conversion patterns, and automatable refactoring recipes. |
| Camunda 7 Adapter | Run existing Camunda 7 delegation code directly in a Camunda 8 environment. |
Migration Analyzer
The Migration Analyzer helps you get a first understanding of migration tasks when moving from Camunda 7 to Camunda 8. It analyzes Camunda 7 model files (BPMN or DMN) and generates a list of tasks required for the migration.
In a second step, it can also convert these files from the Camunda 7 format to the Camunda 8 format. For example, it updates namespaces or renames XML properties if needed.
You can use the Migration Analyzer in the following ways:
- Web Interface: A wizard-like UI built with Java (Spring Boot) and React. Available:
- locally as a Java JAR,
- via Docker, or
- as a free hosted SaaS version.
- CLI: A command-line interface implemented in Java.
The results are available as:
- XLSX: A Microsoft Excel file, including pre-built pivot tables for data exploration.
- CSV: A plain-text comma-separated file, compatible with any spreadsheet tool.
Let's go through this step-by-step:
Installation
Please refer to the Installation Guide for local setup instructions.
To get started right away, try the free SaaS version:
https://migration-analyzer.consulting-sandbox.camunda.cloud/
Analyzing your models using the Web Interface
After local installation, open http://localhost:8080/.
Or use the SaaS deployment (no local setup required).
The wizard is straightforward. Upload one or more models:
Click Analyze and convert:
On this screen you can now:
- Download the analyzer results as Microsoft Excel file (XSLX)
- Download the analyzer results as CSV file
- Download the converted models (individually or as ZIP)
Analysis results contain a list of items, where each row represents an action item required for migrating your solution to Camunda 8. Those items are grouped by severity:
- INFO: No action needed. Diagram conversion can successfully map attributes to the Camunda 8 implementation.
- REVIEW: The convertion will modify some expressions or attributes. Please verify that the intended functionality remains unchanged.
- WARNING: A Camunda 7 concept can not be directly mapped to a Camunda 8 equivalent. Consider reviewing the Camunda 8 roadmap or exploring possible workarounds.
- TASK: Manual changes are required to make the model work in Camunda 8.
This allows you to focus on the most important findings. Tasks can also be grouped by type. For example, changing a JavaDelegate to a JobWorker might appear 100 times in your codebase, but still represents just one recurring pattern.
Pivot tables can help you identify tasks that appear multiple times across different files, providing a comprehensive overview of migration efforts.
Let’s take a closer look at how to use those results.
Understanding analyzer results using Microsoft Excel
The XLSX file includes three tabs:
- AnalysisSummary: Pivot tables and charts that summarize typical migration tasks.
- PivotTable: A large pivot table for dynamic data exploration.
- AnalysisResults: The raw data from the analysis, which you can copy, import, or further process.
You can open the file using Microsoft Excel (desktop or Office 365).
Understanding analyzer results using Google Sheets or LibreOffice
You can also open the XLSX file in Google Sheets, LibreOffice, OpenOffice, or similar tools. The raw data will be imported correctly, but pivot tables will not be preserved.
Alternatively, download the results as a CSV file and import them directly into your preferred tool.
In this case:
- Create your own pivot table in the tool.
- Or copy the contents of the AnalysisResults tab into your own spreadsheet.
For Google Sheets, consider using this Google Spreadsheet template created by Camunda consultants.
Analyzing your models using the CLI
If you prefer the command line over a web interface, the CLI tool is for you. It is ideal for batch conversions or automation.
After installation, run the CLI:
java -jar camunda-7-to-8-migration-analyzer-cli.jar local myDiagram.bpmn --xlsx
You can also prompt a help message that will guide you through all parameters:
java -jar camunda-7-to-8-migration-analyzer-cli.jar local
Missing required parameter: '<file>'
Usage: camunda-7-to-8-migration-analyzer-cli local [-dhoV] [--check] [--csv]
[--delegate-execution-as-job-type] [--disable-append-elements]
[--disable-default-job-type] [--md] [-nr]
[--default-job-type=<defaultJobType>]
[--platform-version=<platformVersion>] [--prefix=<prefix>] <file>
Converts the diagram from the given directory or file
Execute as:
java -Dfile.encoding=UTF-8 -jar camunda-7-to-8-migration-analyzer-cli.jar local
Parameter:
<file> The file to convert or directory to search in
Options:
--check If enabled, no converted diagrams are exported
--csv If enabled, a CSV file will be created containing
the conversions results
--xslx If enabled, a XSLX file will be created containing
the analysis results
-d, --documentation If enabled, messages are also appended to
documentation
--default-job-type=<defaultJobType>
If set, the default value from the
'converter-properties.properties' for the job
type is overridden
--delegate-execution-as-job-type, --delegate-expression-as-job-type
If enabled, sets the delegate expression as the
job type
--disable-append-elements
Disables adding conversion messages to the bpmn xml
--disable-default-job-type
Disables the default job type
-h, --help Show this help message and exit.
--md, --markdown If enabled, a markdown file will be created
containing the results for all conversions
-nr, --not-recursive If enabled, recursive search in subfolders will be
omitted
-o, --override If enabled, existing files are overridden
--platform-version=<platformVersion>
Semantic version of the target platform, defaults
to latest version
--prefix=<prefix> Prefix for the name of the generated file
Default: converted-c8-
-V, --version Print version information and exit.
Converting your models
As mentioned, the Migration Analyzer can also convert BPMN and DMN models for use with Camunda 8.
This includes:
- Updating namespaces
- Adjusting XML structure and properties
- Transforming expressions
Refer to technical details to understand more details around those conversions.
Converted files can be downloaded via the web interface or generated via the CLI.
Extending the conversion logic
You can also extend the conversion logic. See Extending the Migration Analyzer for details.
Expression conversion
JUEL expressions used in Camunda 7 are not supported in Camunda 8. The Migration Analyzer tries to convert simple expressions automatically (see ExpressionTransformer). For an overview of what’s supported, see the ExpressionTransformer test case.
More complex expressions may require manual rewriting. The FEEL Copilot can help with this.
You can also customize or extend the transformer logic as needed.
Data Migrator
The data migrator can copy runtime and audit data from Camunda 7 to Camunda 8.
Camunda is developing the Data Migrator with a first release planned for Camunda 8.8 (October 2025). Iterative improvements might follow.
It provides two important modes that can be applied separately:
- Runtime instance migration mode
- History migration mode
Runtime instance migration mode
Migrate currently running process instances. Running means that these process instances in Camunda 7 are not yet ended and currently wait in some wait-state. This state is persisted in the database and a corresponding data entry needs to be created in Camunda 8, so that the process instance can continue from that state in the new solution.
Requirements and limitations:
- The Runtime Data Migrator needs to access the Camunda 7 database.
- The Runtime Data Migrator needs to access Camunda 8 APIs (which means you can also use this tool when you run on SaaS).
- Multiple Instance is not supported, so process instances that are currently waiting in a multiple instance task cannot be migrated and need to be moved out of that state in Camunda 7 beforehand.
If you need to adjust your process models before migration, you can use process version migration in the Camunda 7 environment to migrate process instances to versions that are migratable to Camunda 8. An interesting strategy can be to define dedicated migration states you want your process instances to pile up in. Another common strategy is to use process instance modification in the Camunda 7 environment to move out of states that are not migratable (for example, process instances within a multiple instance task).
History migration mode (copying audit log data)
Process instances left traces, referred to as History in Camunda 7. These are audit logs of when a process instance was started, what path it took, and so on.
It is important to note that audit data can exist for ended processes from the past, but is also available for currently still running process instances, as those process instances also left traces up to the current wait state.
The History Data Migrator can copy this audit data to Camunda 8.
Audit data migration might need to look at a huge amount of data, which can take time to migrate. In early measurements, migrating 10,000 process instances took around 10 minutes, but the number varies greatly based on the amount of data attached to a process instance (for example, user task instances, variable instances, and so on).
You can run audit data migration alongside normal operations (for example, after the successful big bang migration of runtime process instances) so that it doesn't require downtime and as such, the performance might not be as critical as for runtime instance migration.
Requirements and limitations:
- The History Data Migrator needs to access the Camunda 7 database.
- The History Data Migrator can only migrate to Camunda 8 if a relational database (RDBMS) is used, a feature planned for Camunda 8.9.
- The History Data Migrator needs to access the Camunda 8 database (which means you can only run this tool in a self-managed environment).
- If runtime and history data are migrated at the same time, you will end up with two instances in Camunda 8: a canceled historic process instance and an active new one in the runtime. They are linked by process variables.
Typical choreography of runtime and history migration
As described in the roll-out phase of the migration journey, you will typically use the following sequence of tasks when applying both data migrations while keeping downtimes to a minimum:
- Stop the Camunda 7 solution (normally shut down your application).
- Start the Data Migrator in "running instance migration mode".
- Wait until running instance migration is completed.
- Start the new Camunda 8 solution immediately so migrated process instances can continue right away.
- Start the Data Migrator in "history migration mode".
- The migrator runs until all history data is migrated while Camunda 8 process execution continues in parallel.
With this approach, the duration of history migration doesn't block big bang migrations.
Customization of Data Migrator
You might need to customize the data migration, especially if you used complex data formats in C7 (for example, Java objects) that need to be converted to something Camunda 8 can handle (for example, JSON). As part of this step, you might also need to extract big payloads and binaries (like documents) into an external data store and reference it from the process (using, for example, upcoming document handling possibilities).
Code Converter
Code conversion is described in Code Conversion.
Camunda 7 Adapter
The adapter and its documentation are available on GitHub: Camunda 7 Adapter.