Flowable Migration Guide
In this migration section of the documentation we'll look into migrating from Flowable Open Source to a licensed Flowable product version. In addition this guide explains how to ease migration from other BPM products to Flowable.
Flowable Open Source migration
When migrating from Flowable Open Source to a licensed version of Flowable this can be approached with starting with a model migration or with a migration with the Flowable Open Source runtime data as a starting point. Let's start with looking into using the models, like BPMN, CMMN and DMN, as a starting point and migrate those to a licensed product version of Flowable.
Flowable Open Source models
When the Flowable Open Source models are created using the Flowable Cloud Design application, the models are already fully aligned with the licensed product version of Flowable. In case the models have been created using the Open Source Modeler that was available with Flowable 6.x then the following action is needed. Export the app with models as a deployable artefact and then this zip file can be imported into the Flowable Cloud or on-premise Design application. Note that this works for CMMN, BPMN and DMN models, but not for Forms models. The Form models in Flowable Open Source are very basic and don't match with the wide range of options available with the Flowable Design Form editor. When you have a request to migrate the Open Source Form models to Flowable Design, you can reach out to your Flowable sales contact person or to the general Flowable contact information.
Migrating from the Flowable Open Source runtime data
When migrating the Flowable Open Source models is not sufficient for your use case, there are also options to migrate to a licensed Flowable product version from an existing Flowable Open Source database. The CMMN, BPMN, DMN and event registry engines are fully compatible between Open Source and a license Flowable product, so for this an automatic migration of the database is available. Note that any existing form, content and identity tables are not compatible and need to be removed from the database. Find below the tables that should be removed from your database before doing to automated migration to a licensed Flowable Product version.
| Table name | Description |
|---|---|
| ACT_FO_* | This naming pattern is used for all the form tables and are replaced with FLW_FO_* tables with the licensed Flowable product version. |
| ACT_CO_* | This naming pattern is used for all the content tables and are replaced with FLW_CO_* tables with the licensed Flowable product version. |
| ACT_ID_* | This naming pattern is used for all the identity tables and are replaced with FLW_ID_* tables with the licensed Flowable product version. |
In addition, if you also are running the Open Source Modeler from the same database as well, as this would be the case when you are running the Flowable 6 OSS UI, these are also incompatible. Therefore the following tables should be removed in addition to the tables already mentioned above.
| Table name | Description |
|---|---|
| ACT_DE_* | This naming pattern is used for all the Open Source Modeler tables and are replaced with the Flowable Design tables in the licensed Flowable product version. |
| ACT_ADM_* | This naming pattern is used for the Open Source Admin table and is replaced with the Flowable Control tables in the licensed Flowable product version. |
Authentication and Authorization
When migrating from Flowable Open Source to a licensed Flowable product version, one of the main changes is the difference in the support for authentication and authorization. In Flowable Open Source there's a basic support for users, groups and memberships and there is an option to enable LDAP integration. In the licensed Flowable product version there is a wide range of support for different authentication mechanisms and authorization options. Similar to Flowable Open Source, there is support for users and groups and memberships to be defined in the Flowable database. But the more common usage is to use an external Active Directory or other identity management store to authenticate the user. For authorization a lot more functionality is available in the licensed Flowable product version. For example, there are Security Policy models that allow you to configure the access to work item types on a fine-grained level per role. Also, the REST API takes care of permission checks by default, and a process instance in which the authenticated user has no involvement won't be accessible through the REST API. Also the REST API makes sure that data can't be shared between different tenants, so it's also ensured that data from tenant A is not available to a user from tenant B for example.
No changes in the Open Source REST API
When moving from Flowable Open Source to the licensed Flowable product version the same Open Source REST API will be available. The main difference is that the REST API access has additional permissions that are checked to make sure a user is allowed to have access to for example a case instance or process instance. You can find the documentation of the Open Source REST APIs here. In addition to the Open Source REST API the licensed Flowable product version provides an additional set of REST APIs, including action, data object, service registry, policies etc. You can find the documentation of the additional REST APIs here.
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:
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.
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.
You will now be prompted to select the files to upload. You can upload multiple files at the same time.
Once selected, you can confirm their upload.
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.
Each incompatibility can be expanded to see details, including the location and any hint for resolving the incompatibility.
A tab is provided to show the BPMN XML file contents with line numbers to help see the details.
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.
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.
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.
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!