Model Migration
Based on the previous chapter, Model Versioning, multiple instances started with different deployments run in different definition versions. There is no technical requirement to migrate between the different versions, as long as you keep all APIs compatible. However, depending on how long your processes or cases execute, it might be helpful to migrate them to make it easier to maintain all versions.
When to do migration
A few examples to illustrate when it is good to migrate and when running in the old version is preferred:
- All process and cases are in average completed automatically within a few seconds. In rare cases it takes up to a day until they are completed. There are no regulatory requirements which need to be fulfilled to migrate within a day. In this case, the migration can be skipped, the old version won't be used after a day anymore anyway.
- There are processes or cases which run for multiple years (e.g. 3 years). Releases are done every few months. There are potential regulatory changes to the case or process definitions which need to be fulfilled. Migration should be considered, otherwise in this case different version must be maintained. Even if one migration is skipped, due to the need to upgrade the migration needs to be done at a later point to a new version anyway.
What to consider for migration
Whenever migration is done, there are a few things which need to be configured during migration:
- Wait State: This is the point when an element is waiting for an (external) interaction. E.g. you have a User or Human Task which waits for completion. It can be also something like an async job caused by a timer event or an async flag on a task. Those activities and plan items are relevant for the migration in case they changed.
- New service tasks: Technical tasks doing things in the background are not necessarily relevant for the migration when they do not change. However, it needs to be ensured that the data they potentially produce is also there for the cases/processes they produce. Adding that data as part of the migration allows migrated cases and processes to continue.
- Variables: Especially new variables created or the format change of a variable is important for migration. Those variables must be adapted during the migration process to allow a new process to continue. Not critical, except scaling is an important factor, deleted variables can be cleaned-up.
- New stages, milestones and decorators: When using CMMN, there are other states except the wait state which is important to consider. Allowing an element to repeat or removing the repeat, must be configured during the migration. New stages and milestones potentially must be activated that the case is able to continue.
How to prepare for a migration
When preparing a migration, everything from What to consider for migration need to be taken into an account. Best is to start during development of the second version to think about migration and prepare a document listing the different things which need to be migrated. This contains the elements which have been added and removed and also the impact to other things like variables.
The below table could be used as a starting point:
| Scope Type | Scope Key | Changed Element | Impact to variables | Notes |
|---|---|---|---|---|
| CMMN | customerOnboarding | cmmnStage_9 | / | Repetition added |
| BPMN | createAndSendOffer | bpmnTask_5 | -review | task deleted, go to bpmnTask_1 instead |
| BPMN | createAndSendOffer | bpmnTask_8 | +status | |
| ... | ... | ... | ... | ... |
This table is effort to create it while doing the actual modeling, but it has two major advantages:
- It enables to think about the impact on the migration from the beginning.
- It makes the creation of a migration document easier.
Instead of writing a table, it is also possible to directly write and test the migration document itself, which would make the migration effort smaller. This is especially then helpful when the person doing the modeling has a deep understanding of the migration.
How to do migration
There are a few different ways to do migration, and they depend on the use case and environment.
In development during testing
In lower environments Flowable Inspect can be used for migration. This makes it easy to do the migration, since it's just one button click and either the model fits for an automatic migration or it does not work. For development purposes, this is helpful to not start the execution from the beginning and continue from the point on which an error occured. This approach is meant to be used for small fixes and testing the changes quickly.
To get started Flowable Inspect check out the Flowable Inspect User Guide.
Once Flowable Inspect is opened, and a new version was published, for an existing instance the migration button gets visible:
The migration button is only visible on case and process level, not on task level. The hierarchy can be used to navigate to the next level of a process. A migration will only migrate the one process selected and does not do migration for child or parent processes if applicable.
In staging and production environments
For the usage in higher environments the migration steps need to be defined and tested. There are two approaches:
Manual Migration with Flowable Control
Flowable Control allows to trigger case and process migration either for a single case/process instance or for a case/process definition. This is especially useful for hotfixes with a small migration mapping which can be easily executed through the UI interface.
To execute the migration, navigate to the definition or instance and select the "Migrate" button. Flowable will guide through the migration and the migration can be executed with the "Execute Migration" button at the end.
Automated Migration with a Migration Document
Flowable Control allows to do a quick migration, however there are manual steps involved which makes testing for the migration in a lower environment harder. There are APIs to execute the migration which makes it possible to specify the migration steps and execute the exact same steps in multiple environments.
Please follow the following REST API documentations on how migration can be done: