Process instance migration made easy

jBPM 6 comes with an excellent deployment model based on knowledge archives which allows different versions of given project to run in parallel in single execution environment. That is very powerful but at the same time brings some concerns about how to deal with them, to name few:

  • shall users run both old and new version of the processes?
  • what shall happen to already active process instances started with previous version?
  • can active versions be migrated to newer version and vice versa?

While there might be other concerns, one of the most frequently asked question is such situation is: can I migrate active process instance?

So can we do process migration with jBPM?

The straight answer is - YES

... but it was not easily available to be performed via jbpm console (aka kie-workbench). This article is about to introduce solution to this limitation by providing ... knowledge archive that can be deployed to your installation and simply used to migrate any process instance. I explicitly use term "migrate" instead of upgrade because it can actually be used in both directions (from lower to higher version or from higher to lower version).

So there are quite few things that might happen when such operation is performed. All depends on the changes between versions of the process definition that are part of the migration. So what does this process migration comes with:

  • it can migrate from one process to another within same kjar
  • it can migrate from on process to another across kjars
  • it can migrate with node mapping between process versions 

While the first two options are simple, the third one might require some explanation. What is node mapping? While doing changes in process versions we might end up in situation that nodes/activities are replaced with another node/activity and by that when migrating between these versions mapping needs to take place. Another aspect is when you would like to skip some nodes in current version (see second example).

NOTE: mapping will happen only for active nodes of the process instance that is being migrated.

Be careful what you migrate...

Migration does not affect any data so please take that into account when performing migration as in case there were changes on data level process instance migration will not be able to resolve potential conflicts and that might lead to problems after migration.

To give you some heads up about how does it work, here comes two screencasts that showcase its capabilities in actions. For this purpose we use our standard Evaluation process that is upgraded with new version and active process instance is migrated to next version.

Simple migration of process instance

This case is about showing how simple it can be to migrate active process instance from one version to another:
  • default org.jbpm:Evaluation:1.0 project is used which consists of single process definition - evaluation with version 1
  • single process instance is started with this version
  • after it has been started, new version of evaluation process is created
  • upgraded version is then released as part of org.jbpm:Evaluation:2.0 project with process version 2
  • then migration of the active process instance is performed
  • results of the process instance migration is the illustrated on process model of active instance and as outcome of the process instance migration

Process instance migration with node mapping

In this case, we go one step further and add another node to Evaluation process (version 2) to skip one of the nodes from original version. So to do that, we need to map nodes to be migrated. Steps here are almost the same as in first case with the difference that we need to go over additional steps to collect node information and then take manual decision (over user task) what nodes are mapped to new version. Same feedback is given about results.

Ready to give it a go?

To play with it, make sure you have jBPM version 6.2 (currently available at CR level from maven repository but soon final release will be available) and then grab this repository into your jbpm console (kie-wb) workspace - just clone it directly in kie-wb. Once it's cloned simply build and deploy and you're ready to migrate any process instance :).

Feedback, issues, ideas for improvements and last but not least contribution is more than welcome.


  1. Hello,
    is it possible to keep two different process definition?, or I need always migrate the versions?
    What is the right way for process versioning in jbpm 6.1.0 ?
    I tryed to use kjar's with deployment by :deploymentService.deploy(deploymentUnit), but even that I need to show right "groupId, artifactId, version" in RuntimeEnvironmentBuilder.

    1. yes, that is perfectly valid scenario to have multiple versions of given project deployed and running concurrently on same runtime environment. No need to migrate process instances unless needed.

      Correct, whenever you interact with processes from different projects you need to use their deployment identifier (GAV) so it can find the one you need to work with. Otherwise there will not be possibility to figure out which project's process shall be started.

      Note in 6.2 there will be possibility to specify 'latest' instead of actual version number to start process from latest version of given project defined as group and artifact id.

  2. ok, this is nice to separate different versions of process in different jar's.
    but - if I use the environment = RuntimeEnvironmentBuilder.getDefault("test", "processes", "1.0.2")
    then I can't complete tasks by taskId started from the previous jar. -"1.0.1"
    getRuntimeEngine().getTaskService().complete(taskId, actorId, null) created by the enviroment above throw NPE.
    Please tell me - How is possible to manage (complete,claim) previous tasks with correct enviroment?

    1. you need to use the same version of the runtime manager for the version your processes and tasks belong to. As in theory they can be configured to use different data bases or different listeners, etc. So make sure you always use the right runtime manager otherwise you'll have unexpected issues such as NPE...

    2. ok, so I should develop myself the logic which choose proper enviroment for old process instances.

    3. yes, jbpm by itself does not know what version you'd like to use.

      btw, could you pastebin the complete exception you're getting there, maybe there is another reason of that NPE as well. Best to start new thread at user forum or on mailing list.

  3. hello how do we migrate process instances when we have embedded JBPM6 in our application ( our process map has changed and we have new swim-lanes and nodes added and we need to migrate the active process instances to use the new diagram )

    1. you can run the process as stand alone program that would get the information and automatically upgrade. Or simply use the logic behind the process to migrate it manually by calling the API.

  4. Thanks for your post and process.

    I have a problem when i try migrate, my version is 6.2.0.Final.

    How can i upgrade your process-migration for my version?

  5. Hi,
    I used this approach to migrate and after successful migrating the process Instance in some scenarios it is not working and throwing error even though the node after human task is same.

    Please let me know how to fix this issue so that Human Task can complete.
    Your valuable input will be appreciated.

    JBPM Version : 6.3
    Design : Human task (Reserved) > exor split > Human Task/OR Node

    The error thrown is :

    Caused by: java.lang.ClassCastException: org.jbpm.workflow.core.node.Split cannot be cast to org.jbpm.workflow.core.node.HumanTaskNode
    at org.jbpm.workflow.instance.node.HumanTaskNodeInstance.getHumanTaskNode(HumanTaskNodeInstance.java:32)
    at org.jbpm.workflow.instance.node.HumanTaskNodeInstance.triggerCompleted(HumanTaskNodeInstance.java:85)
    at org.jbpm.workflow.instance.node.WorkItemNodeInstance.workItemCompleted(WorkItemNodeInstance.java:385)
    at org.drools.persistence.jpa.processinstance.JPAWorkItemManager.completeWorkItem(JPAWorkItemManager.java:147)

    1. looks like you migrated to different node. This can be due to removed nodes from the first version which then made it node id sequence to be out of sync or you mapped the nodes incorrectly. I'd recommend to move to 6.5 which has the migration included in the code base that is much improved compared to this version.


    2. Thanks for your reply.
      I was assuming that it must be because of the wrong node mapping. But when I compare the process diagram from old to new, the node sequence is same i.e Human Task (active) > EXOR Split > Human Task.
      Can you help on how to check which node mapping is wrong and how to correct that now.
      Awaiting for you response.

  6. Dears
    How to migrate processes from JBPM 3 to JBPM 6.5???

  7. When we start a process via API, we only send containerId and processId. We want to know what is the usage of attribute version of bpmn files. Thanks in advance!

    1. version on process definition is considered as meta data only and is not used by process engine for execution.

    2. Thanks for your answer. We are using kie-server as engine. We have a maven artifact with the bpmn file and our custom work item handlers for each container (one container - one business process).

      Per example, process_test 1.0.0 / container_process_test_1_0_0, process_test 2.0.0 / container_proces_test_2_0_0.

      If we fix a bug in a custom work item handler, we heave to deploy a new container with it (let's say process_test 3.0.0 with process_test 3.0.0). What can we do to apply this fix in the previous deployed containers? If we change the artifact version for each related container, the fix in the custom work item handler will work for everyone of them, but what if the bpmn file was modified in process_test 3.0.0 with a new feature? I assume it'll break the flow in live instances...

      If we could manage the bpmn process version (container_process_test_1_0_0 using process_test 3.0.0 but with bpmn file version 1.0.0), maybe there would be a solution, what do you think?

    3. Ariel,

      in general it all depends on type of the change. If you change the process definition that means usually a need for migration unless it's a backward compatible change which rarely is. If it's work item handler change then you most likely can avoid migration and just bump the version (or use version range) for work item handler jar dependency.

      In your case bpmn process version is kjar/container version as it is one to one if I got it right.

  8. can we migrate process instances deployed in kie-server ?

    1. yes, since version 6.5 there is process migration endpoints in kie server as well, so it is actually even easier as there is no need to build anything yourself. Here you can find some test cases using KIE Server Client: https://github.com/kiegroup/droolsjbpm-integration/blob/6.5.x/kie-server-parent/kie-server-tests/kie-server-integ-tests-jbpm/src/test/java/org/kie/server/integrationtests/jbpm/admin/ProcessInstanceMigrationIntegrationTest.java

  9. Hi Maciej,
    I'm using 6.4 and trying to migrate a process from kie-server the respective tables got updated and the process is migrated to the intended version, but when i signal/approve the task for the migrated process, nothing is happening. What could be the root cause?

    1. One finding after migration is, in processinstanceinfo table's BLOB the deploymentid is not updated but the processid has been updated. After updating the blob object with latest deploymentid it worked.

      Before migration:
      ¬í wÑ RuleFlow

      RuleFlow 5 POC.HelloWorld ( :
      " ( ` j processStartEventj%_E9EA865F-D42C-49ED-A087-CD945F49F98Br)
      %_FEB7758B-A47C-4E19-9E8F-DC190171FD1D z
      HelloWorld€ Š com.san.vin.kum:POC:1.0

      after migration:
      ¬í wÒ RuleFlow

      RuleFlow 5 POC.HelloWorld2 ( :
      " ( ` j processStartEventj%_E9EA865F-D42C-49ED-A087-CD945F49F98Br)
      %_FEB7758B-A47C-4E19-9E8F-DC190171FD1D z
      HelloWorld€ Š com.san.vin.kum:POC:1.0

    2. I'd recommend do you process instance migration that comes with kie server instead of using this article approach - there is out of the box support for it since 6.5 so it might be worth upgrading

      here is a test case that uses kie server client https://github.com/kiegroup/droolsjbpm-integration/blob/6.5.x/kie-server-parent/kie-server-tests/kie-server-integ-tests-jbpm/src/test/java/org/kie/server/integrationtests/jbpm/admin/ProcessInstanceMigrationIntegrationTest.java#L79

    3. Thanks Maciek! Will upgrade to 6.5 asap.
      But if I want to make it(process-migration) work, where actually i need to change in MigrationManager.java to update the processinstanceinfo table with the latest deploymentid?

    4. yes that would be the short term solution

  10. Hi Maciej, Can you please share some example code snippet to do simple process instance migration in JBPM 6.0 ? I'm new to JBPM and I've requirement to migrate existing running process to newer version of process instance after deployment of new version(kjar).