Skip to main content

Flowable Migration Guide

This guide explains how to ease migration from other BPM products to Flowable.

Legacy BPM migration steps​

Moving from a legacy BPM product to Flowable can be straight-forward with several options available to achieve this. For some legacy products, the migration can automatically include existing historical data as well as in-flight, active process instances. For these migrations, there is a common sequence of steps to take.

Step One: Validation​

The first step is to validate and adjust any existing BPMN models so they can be executed on Flowable's runtime engines. We provide Flowable Leap (see below) to aid with this, by either uploading BPMN model files or connecting it to a database with deployed BPMN process models. The tool will validate and highlight incompatibilities, if any. In many cases, you will not need to adjust your models, as Flowable's DUAL runtime technology can automatically convert many common legacy extensions. If unsupported legacy extensions are reported, some suggested changes may be provided. Make the changes to your BPMN models, either with a text editor or Flowable Design, then upload and validate them again.

Step Two: Migrate database​

Install Flowable and configure it to use your existing (or duplicated) database. If you have in-flight process instances, you may need to enable the Flowable 5 compatibility engine. This works for any Flowable 5 equivalent engine (such as Activiti 5 and Camunda 7).

More concretely, the flowable5-compatibility (with groupId org.flowable) needs to be added as a dependency and the process engine needs to be configured as follows:

processEngineConfiguration.setFlowable5CompatibilityEnabled(true);
processEngineConfiguration.setFlowable5CompatibilityHandler(new DefaultFlowable5CompatibilityHandler());

The first time you start Flowable, by default it will automatically update the database schema to be compatible with the latest Flowable services. You would normally do a test migration against a copy of your existing installation before the actual migration, having done backups and all the other standard good practice tasks.

Step Three: Optional updates​

If you decided to modify any of the BPMN models, you will need to redeploy the updated models, so they can be executed. The redeploy can be done programmatically (through the RepositoryService) or through alternative ways like using Flowable Control. Any new process instance will be started using this new process definition.

In certain use cases, such as for example using class delegates for a service task, a change to the code will need to be applied to make sure the correct implementation is available on the Java classpath. In general, the tool will advise this:

flowable leap 0

By default, any running instance will be handled by the Flowable 5 compatibility engine. In case you want to force such instances to not use the compatibility engine, you will need to perform process instance migration in Flowable Control, to ensure they use the updated model definition.

Step Four: ...and relax​

Get learning about all the fantastic capabilities of Flowable so you can really start to exploit the possibilities for your work!

Flowable Leap​

Flowable Leap (Legacy Execution Analysis of Processes) is a tool that can analyze BPMN models from other BPM products, such as Camunda and Activiti, and highlight any incompatibilities with running them on Flowable. Flowable Leap is available online and also as a download.

flowable leap 1

Free online use of Flowable Leap​

Flowable Leap is available online for free use to analyse BPMN XML files. Get access from https://go.flowable.com/leap-migration. The online version allows any number of BPMN XML files to be uploaded without sign-in, with the uploads being available while the browser session is active (up to 30 minutes after your last activity on it). Other users don't have access to the uploads, and copies of uploads are not retained. The online version of Flowable Leap cannot connect to your database to analyze BPMN models.

Uploading BPMN models​

To upload your BPMN models for analysis, click the Import menu option. This will open a dialog to choose what import method to use. For the online version, only the file upload option will be enabled. Select it.

flowable leap 2

You will now be prompted to select the files to upload. You can upload multiple files at the same time.

flowable leap 3

Once selected, you can confirm their upload.

flowable leap 4

Once uploaded, the Uploads menu option will be updated with a list of the analyzed models, with the most recent one selected. If there are any incompatibilities, they are listed.

flowable leap 5

Each incompatibility can be expanded to see details, including the location and any hint for resolving the incompatibility.

flowable leap 6

A tab is provided to show the BPMN XML file contents with line numbers to help see the details.

flowable leap 7

A button is also provided for each model to download the list of incompatibilities in CSV format, so they can be opened in Microsoft Excel and other applications.

Offline installation of Flowable Leap​

A download for offline use of Flowable Leap is also available from https://go.flowable.com/leap-migration. The tool is provided as a Java JAR file, so requires a recent version of Java to be installed (for example from https://adoptium.net/releases.html).

Once downloaded, it can be started using the command:

java -jar flowable-leap.jar

This will start a web application on port 8080 by default, so can be accessed using http://localhost:8080/. All the options available in the online version are also available in the offline version. There is an additional method for selecting models for analysis, by connecting to databases that contains your existing BPM installations.

flowable leap 8

You need to specify the database connection details for your legacy installation. Flowable Leap includes drivers for H2, MySQL and PostgreSQL, so can connect to these without further configuration.

flowable leap 9

For each legacy database you connect to, a menu item is added to the left-hand side (you can choose the name in the connection details), from where you can see the BPMN models that have been extracted and analyzed.

flowable leap 10

A useful option is available for each model to download a BPMN XML file version of the extracted model.

Configuration options​

The default configuration for Flowable Leap can be overridden using external Spring Boot properties, for example by placing an application.properties file in the same folder as the jar.

The default properties for Flowable Leap are:

# Configures the maximum file size when uploading files
spring.servlet.multipart.max-file-size=10MB

# Database configuration
spring.datasource.url=jdbc:h2:mem:migration
spring.datasource.username=flowable
spring.datasource.password=flowable

When using another database than H2, MySQL or PostgreSQL, the JDBC database driver needs to be added to the classpath of the application. This can be done setting the -Dloader.path=somefolder setting of Spring boot. In

Unsupported BPMN Constructs​

The compatibility engine and validation rules have been implemented taking into account those BPMN constructs and patterns which we have seen prevalent at customers. In case an incompatibility is discovered that is not shown in the validations or not covered by the compatibility engine, don't hesistate to contact your Flowable representative!