jBPM runtime

Please take some time to read through the official documentation of jBPM’s Core Engine API before proceeding here.


Magnolia’s jBPM integration takes advantage of the new Runtime Manager concept.

_The runtime manager manages the KIE session according to a predefined strategy. The following strategies are available:

  • Singleton: The runtime manager maintains a single KieSession and uses it for all the requested processes.

  • Per Request: The runtime manager creates a new KieSession for every request.

  • Per Process Instance: The runtime manager maintains mapping between process instance and KieSession and always provides the same KieSession whenever working with a given process instance.

Magnolia uses the singleton strategy, which means the RuntimeManager maintains a single instance of RuntimeEngine and in turn a single instance of KieSession (and TaskService). This is the easiest approach and how it used to work in jBPM 5.x. But it comes with a performance penalty because of the synchronized access to the RuntimeEngine.

An alternative to this would be the per process strategy, where the RuntimeManager maintains a strict relationship between KieSession and ProcessInstance. Currently, the underlying JCR persistence is lacking the possibility to store this relationship using the so called Correlation Key.


In jBPM the Runtime Environment is used by the RuntimeManager and encapsulates all important configuration that it requires for execution. It has to be fully instantiated and configured before the manager gets started and should not be altered afterwards.

Magnolia has its own implementation of the RuntimeEnvironment which takes care of the following during initialization:

  • Configure JCR persistence related classes.

  • Load process definitions

  • Provide the necessary implementations used by the runtime (see Magnolia’s implementation of RegisterableItemsFactory) such as:

    • Workitem handlers

    • Process event listeners


public class MgnlRuntimeEnvironment extends SimpleRuntimeEnvironment {

    public MgnlRuntimeEnvironment(WorkflowDefinitionRegistry workflowRegistry, RegisterableItemsFactory registerableItemsFactory, ComponentProvider componentProvider) {

    public void init() {
        addToConfiguration("drools.workItemManagerFactory", JcrWorkItemManagerFactory.class.getName());
        addToConfiguration("drools.processInstanceManagerFactory", JcrProcessInstanceManagerFactory.class.getName());
        addToConfiguration("drools.processSignalManagerFactory", JcrSignalManagerFactory.class.getName());

        addToEnvironment(EnvironmentName.PERSISTENCE_CONTEXT_MANAGER, componentProvider.newInstance(JcrProcessPersistenceContextManager.class));



Class diagram

The most important classes involved in setting up the jBPM Runtime and communicating with the engine.

UML runtime

Starting the jBPM engine

This sequence diagram illustrates how the Runtime is initialized during module startup. After startup the WorkflowManager has a fully initialized RuntimeManager which allows communicating with the engine.

Module start

Launching a process

This sequence diagram shows how a process gets launched using the LaunchWorkflowCommand.

Launch process


DX Core



This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules
6.3 beta

Magnolia 6.3 beta

Magnolia 6.3 is in beta. We are updating docs based on development and feedback. Consider the 6.3 docs currently in a state of progress and not final.

We are working on some 6.3-beta known issues during this phase.