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.

jBPM documentation on Processes:

jBPM6 allows you to execute processes defined using the BPMN 2.0 XML format. That means that you can use all the different jBPM6 tooling to model, execute, manage and monitor your business processes using the BPMN 2.0 format for specifying your executable business processes. Actually, the full BPMN 2.0 specification also includes details on how to represent things like choreographies and collaboration. The jBPM project however focuses on that part of the specification that can be used to specify executable processes.

Executable processes in BPMN consist of a different types of nodes being connected to each other using sequence flows. The BPMN 2.0 specification defines three main types of nodes:

  • Events: They are used to model the occurrence of a particular event. This could be a start event (that is used to indicate the start of the process), end events (that define the end of the process, or of that subflow) and intermediate events (that indicate events that might occur during the execution of the process).
  • Activities: These define the different actions that need to be performed during the execution of the process. Different types of tasks exist, depending on the type of activity you are trying to model (e.g. human task, service task, etc.) and activities could also be nested (using different types of sub-processes).
  • Gateways: Can be used to define multiple paths in the process. Depending on the type of gateway, these might indicate parallel execution, choice, etc.

jBPM6 does not implement all elements and attributes as defined in the BPMN 2.0 specification. We do however support a significant subset, including the most common node types that can be used inside executable processes.

Please read the whole  Processes chapter in jBPM documentation.

Visual representation of a process

BPMN2 files are XML files. You can model them in a visual modeler.

Here is a visual representation of a simple process consisting only of start and end events and one executable task.

Recommended modeler

jBPM can execute any process that is described using the standard BPMN 2.0 XML format. You can use any modeler application that supports the format. As always with standardized formats and their implementations, there are shortcomings no matter which one you choose. At Magnolia we use the Eclipse BPMN2 modeler plugin. Feel free to add other recommendations as comments in this document.

Loading a process

Magnolia provides a configurable registry for processes under the workflows folder in a module. Add custom workflow process definitions in the workflows folder. All processes defined under the folder will be loaded by the jBPM engine upon restart.

<module name>/workflows/activate.yaml
id: com.example.workflow.CustomActivation
name: activate
resourcePath: CustomActivation.bpmn
type: bpmn
Node nameValue
















The folder which contains a list of workflow definitions. The name of the folder must be workflows.



The name of the workflow. The name is arbitrary but must be unique.



Used for identifying processes inside jBPM. 



The name used in Magnolia to identify the process. This is called from your command launching the workflow.



Path to the .bpmn file inside your module's resource directory.



Magnolia currently only loads processes of type bpmn.



Instead of using the resource path you can use the XML definition directly. This will override the resourcePath.

Launching a process

Workflow processes are launched using commands. As an example we have two commands defined inside the workflow command catalog.

The activate command chain inside the workflow catalog consists of two commands: version and activate. When you launch this chain the content is first versioned and then activated. The activate command launches the activate workflow.

The workflow property defines which workflow is launched. The property maps to the name of the registered process in the process registry.


Magnolia comes with two commands for launching workflows. Both commands can be configured in the class property of your command configuration.

  • info.magnolia.module.workflow.commands.LaunchWorkflowCommand: Use this command to launch arbitrary processes not related to content and publishing. This command launches the configured workflow and passes parameters from the context to jBPM engine, including the current user. The command also checks permissions and enforces the user to have write permission in the workflow workspace.
  • info.magnolia.module.workflow.commands.PublicationWorkflowCommand: Extends the first command and is intended for publication processes. This command allows you to configure a workflow mapping. It enforces the current user to have read permission on the content node being published.

Publication command

While the publication process is launched by the PublicationWorkflowCommand the process itself will again launch a command for the actual publication. By default this is the activate command from the default catalog defined inside the Activation module or in case personalization is installed it uses the personalizationActivation command. The command is configurable.

Workflow mappings

You can define different processes to be launched based on sub paths of your node. So in case you want to handle the publication of some content inside your tree differently you can configure this inside your command definition, like this:

When configuring a workflow mapping create a new catalog inside your app. Otherwise the mapping is applicable for the publication of all content.

Input and output parameters

Modeling of a process is mostly about defining flows of executable tasks. However, it all boils down to working with data. Data can be passed as parameters into the process from the very beginning and has to carefully be mapped and manipulated from one task to another.

Use Magnolia's commands to launch a process. This allows you to pass parameters to the process using command context attributes consisting of the parameters passed to the following call:

Passing parameters using the CommandsManager
info.magnolia.commands.CommandsManager#executeCommand(final String catalogName, final String commandName, final Map<String, Object> params)

Furthermore, you can consolidate parameters into a named map which you can reference from within jBPM. Add the parameterMapName property under the commands configuration:

Here's how you can reference the map in the BPMN2 modeler:

Please refer to the tutorial for a step-by-step explanation.


We have put together a step-by-step tutorial on how to create, load and launch custom process.