Migrating from Activiti 5.15.1 to Flowable 7.2 - Best practices for schema migration and in-flight process handling

Flowable Engine
1

We are migrating our case management application from Activiti 5.15.1 to Flowable 7.2 (Java 17, Spring 6.2.x, MariaDB/PostgreSQL, Liquibase 4.33.0).

As we started investigating the migration process we hit the following error on startup:

FlowableException: couldn't upgrade db schema: alter table ACT_RU_TIMER_JOB add column SCOPE_ID_ varchar(255)

Caused by: SQLSyntaxErrorException: Table 'ACT_RU_TIMER_JOB' doesn't exist

It appears Flowable detects the existing Activiti 5.x schema and attempts to run upgrade scripts, but the schema is too old for the upgrade path to succeed. This ACT_RU_TIMER_JOB didn’t exist in Activiti 5.x.

We have the folowing questions:

  1. Is there a supported upgrade path?

We understand the schema changed significantly between these versions. Is there official migration tooling or a documented incremental upgrade path or is clean schema recreation the only realistic option?

We already tried to add the migration scripts 5.15.1 to 6.1 from the flowable-engine and that went well.

  1. How should we handle in-flight process instances?

We have process instances that may be active at the time of migration. Are these recoverable in Flowable 7.2 if the schema is recreated, or is the internal execution model different enough that resumed instances would be unreliable? What is the recommended production cutover strategy in this scenario?

  1. Should we use the Flowable 5 compatibility engine?

We noticed Flowable ships with a Flowable 5 compatibility engine specifically for running legacy Activiti/Flowable 5 process instances. Is this the recommended bridge for our situation — and if so, what are the limitations and known issues we should be aware of before committing to that approach?

Any guidance would be greatly appreciated, thanks.

2

Hey @nadel,

I think that this should indeed work. We have Flowable Migration Guide : Flowable or Activiti v5 to Flowable V6 · Flowable Open Source Documentation that can be used as a guide. In any case, in your case I would maybe suggest that you first do Activiti 5.15.1 to Flowable 5.23.0 and then from there you can go to Flowable 7.2.

This two questions are linked to each other. Yes, in your case you’ll need the Flowable 5 compatibility engine. Which means that you would need to add those dependencies and enable it. There is nothing else special that you need to do. During runtime we detect whether the runtime instance is from v5 and if it is then it will run on the old architecture. All the new deployed process definitions are going to start instances using the new architecture.

From a public API point of view nothing changes, e.g. if you use the ProcessInstanceQuery you’ll get all the running process instances, both the ones from v5 and the new ones. We are reusing the same tables, so things should work without issues.

Cheers,
Filip