Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

3.10. Updating Rule Flows

Over time, your business processes are likely to evolve as you refine them or due to changing requirements. You cannot actually update a rule flow to mirror this but you can deploy a new version of it. The old process will still exist because existing process instances might still need the old one's definition. Because of this, you have to give the new process different ID., but you can use the same name and version parameter.
Whenever a rule flow is updated, it is important that you determine what is to happen to the already process instances that are already running. Here are your options:
  • Proceed: you allow the running process instance to proceed as normal, using the definition as it was defined when the instance was started. In other words, the already-running instance will proceed as if the rule flow has not been updated. Only when you start new instances, will the updated version be used.
  • Abort (and restart): you abort the running instance. If necessary, restart it so that it will use the new version of the rule flow.
  • Transfer: you migrate the process instance to the new process definition, meaning that it will continue executing based on the updated rule flow logic.
By default, the Rule Flow Engine uses the "proceed" approach.

3.10.1. Rule Flow Instance Migration
Copy link

A rule flow instance contains all the run-time information needed to continue execution at some later point in time. This includes all of the data linked to this process instance (stored in variables), and also the current state of the process diagram. For each active node, a node instance represents this.
A node instances also contain an additional state linked to the execution of that specific node only. There are different types of node instances, one for each type of node.
A rule flow instance only contains the run-time state. It is only indirectly linked to a particular rule flow (via an ID. reference) that represents the logic that it needs to follow when running. As a result, to update a running process instance to a newer version of the new rule flow, you simply have to update the linked process ID.
However, this does not take into account fact that you might need to migrate the state of the rule flow instance as well. In cases where the process is only extended and all existing wait states are kept, this is relatively straightforward, as the run-time state does not need to change at all. However, at other times a more sophisticated mapping may be needed. For example, when you remove an existing wait state, or split into multiple wait states, you cannot update the existing rule flow instance. Likewise, when a new process variable is introduced, you might need to initialize that variable correctly prior to using it in the remainder of the process.
To handle this, you can use the WorkflowProcessInstanceUpgrader to upgrade a rule flow process instance to a newer one. To use this tool, you will need to provide the process instance and the new process' ID. By default, the Rules Flow Engine will automatically map old node instances to new ones with the same ID but you can provide a mapping of the old (unique) node ID. to the new node ID. (The unique node ID is the node ID., preceded by the node IDs of its parents, separated by a colon). These IDs allow you to uniquely identify a node when composites are used (as a node ID. is only unique within its node container.)
Here is an example: 
// create the session and start the process "com.sample.ruleflow"
KnowledgeBuilder kbuilder = ...
StatefulKnowledgeSession ksession = ...
ProcessInstance processInstance = ksession.startProcess("com.sample.ruleflow");

// add a new version of the process "com.sample.ruleflow2"
kbuilder = KnowledgeBuilderFactory.newKnowledgeBuilder();
kbuilder.add(..., ResourceType.DRF);
kbase.addKnowledgePackages(kbuilder.getKnowledgePackages());

// migrate process instance to new version
Map<String, Long> mapping = new HashMap<String, Long>();
// top level node 2 is mapped to a new node with ID 3
mapping.put("2", 3L); 
// node 2, which is part of composite node 5, is mapped to a new node with ID 4
mapping.put("5.2", 4L); 
WorkflowProcessInstanceUpgrader.upgradeProcessInstance(
   ksession, processInstance.getId(),
   "com.sample.ruleflow2", mapping);
Copy to Clipboard Toggle word wrap
If this kind of mapping is still insufficient, you can generate your own custom mappers for specific situations. To do so, follow these instructions:
Firstly, disconnect the process instance.
Next, change the state accordingly.
Finally, reconnect the process instance.
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red Hat