Magnolia 5.7 reached extended end of life on May 31, 2022. Support for this branch is limited, see End-of-life policy. Please note that to cover the extra maintenance effort, this EEoL period is a paid extension in the life of the branch. Customers who opt for the extended maintenance will need a new license key to run future versions of Magnolia 5.7. If you have any questions or to subscribe to the extended maintenance, please get in touch with your local contact at Magnolia.

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. 

RuntimeManager has been introduced to simplify and empower usage of knowledge API especially in context of processes. It provides configurable strategies that control actual runtime execution (how KieSessions are provided) and by default provides following:

  • Singleton - runtime manager maintains single KieSession regardless of number of processes available
  • Per Request - runtime manager delivers new KieSession for every request
  • Per Process Instance - runtime manager maintains mapping between process instance and KieSession and always provides same KieSession whenever working with given process instance

Runtime Manager is primary responsible for managing and delivering instances of RuntimeEngine to the caller.

-- jBPM Core Engine: RuntimeManager

Magnolia uses a 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.

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.

Launching a process

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