Skip to main content
Version: 8.8

Diagram Converter

With Diagram Converter, you'll get an initial understanding of the migration tasks you'll need to perform when moving from Camunda 7 to Camunda 8. It analyzes Camunda 7 diagram 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 and renames XML properties, if needed.

You can use the Diagram Converter in the following ways:

  • Web Interface: A wizard-like UI built with Java (Spring Boot) and React. Available versions:
    • Java JAR
    • Docker
    • Free, hosted SaaS
  • 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.

In the following sections, you'll learn how to:

Install the Diagram Converter​

Refer to the Installation Guide for local setup instructions.

To get started right away, try the free SaaS version.

Analyze your diagrams using the Web Interface​

Open the Diagram Converter:

Upload one or more diagrams:

Upload your diagrams

Click Analyze and convert:

See results

On this screen you can:

  • Download the analyzer results as a Microsoft Excel file (XLSX)
  • Download the analyzer results as a CSV file
  • Download the converted diagrams (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. These items are grouped by severity:

  • INFO: No action needed. Diagram conversion can successfully map attributes to the Camunda 8 implementation.
  • REVIEW: The conversion 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 diagram 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.

Next, you'll learn how to use those results.

Analyze results in Microsoft Excel​

The MS Excel result

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 process further.

You can open the file using Microsoft Excel (desktop or Office 365).

Analyze results in 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 won't be preserved.

Alternatively, download the results as a CSV file, and import them directly into your preferred tool.

In this case, either:

  • Create your own pivot table in the tool.
  • Copy the contents of the AnalysisResults tab into your own spreadsheet.

For Google Sheets, consider using this Google Spreadsheet template created by Camunda consultants.

The Google Sheet

Analyze results with 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 installing, run the CLI:

java -jar camunda-7-to-8-diagram-converter-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-diagram-converter-cli.jar local

Missing required parameter: '<file>'
Usage: camunda-7-to-8-diagram-converter-cli local [-dhoV] [--check] [--csv]
       [--add-data-migration-execution-listener]
       [--data-migration-execution-listener-job-type=<dataMigrationExecutionListenerJobType>]
       [--disable-append-elements]
       [--always-use-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-diagram-converter-cli.jar local

Parameter:
      <file>                 The file to convert or directory to search in
Options:
      --add-data-migration-execution-listener
                             Add an execution listener on blank start events
                               that can be used for the Camunda 7 Data Migrator
      --always-use-default-job-type
                             Always fill in the configured default job type,
                               interesting if you want to use one delegation
                               job worker (like the Camunda 7 Adapter).
      --check                If enabled, no converted diagrams are exported
      --csv                  If enabled, a CSV file will be created containing
                               the results for the analysis
  -d, --documentation        If enabled, messages are also appended to
                               documentation
      --data-migration-execution-listener-job-type=<dataMigrationExecutionListen
        erJobType>
                             Name of the job type of the listener. If set, the
                               default value from the 'converter-properties.
                               properties' is overridden
      --default-job-type=<defaultJobType>
                             Job type used when adjusting delegates. If set,
                               the default value from the 'converter-properties.
                               properties' is overridden
      --disable-append-elements
                             Disables adding conversion messages to the bpmn xml
  -h, --help                 Show this help message and exit.
      --keep-job-type-blank  Sets all job types to blank so that you need to
                               edit those after conversion yourself
      --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.
      --xlsx                 If enabled, a XLSX file will be created containing
                               the results for the analysis

Convert your diagrams​

As mentioned, the Diagram Converter can also convert BPMN and DMN diagrams for use with Camunda 8.

This includes:

  • Updating namespaces
  • Adjusting XML structure and properties
  • Transforming expressions

Converted files can be downloaded via the web interface or generated via the CLI.

Extend the conversion logic​

You can also extend the conversion logic. See Extending the Diagram Converter for details.

Convert expressions​

JUEL expressions used in Camunda 7 aren't supported in Camunda 8. The Diagram Converter tries to convert simple expressions, automatically. For an overview of what’s supported, see the ExpressionTransformer test case.

You may have to manually rewrite more complex expressions. The FEEL Copilot can help with this.

You can also customize or extend the transformer logic as needed.