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.
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. The registry is under the
workflows folder in a module.
id: Used for identifying processes inside jBPM.
name: The name used in Magnolia to identify the process. This is called from your command launching the workflow.
resourcePath: Path to the .bpmn file inside your module's resource directory.
type: Magnolia currently only loads processes of type
definition: Optional. Instead of using the resource path you can use the XML definition directly. This will override the
When you add a new workflow process create a
workflows folder in your module configuration. All processes defined under the folder will be loaded by the jBPM engine upon restart.
Restart Magnolia when you add a new workflow process.
To get more insight into creating custom processes see Creating a custom workflow process.
Launching a process
Workflow processes are launched using commands. As an example we have two commands defined inside the
workflow command catalog.
activate command chain inside the
workflow catalog consists of two commands:
activate. When you launch this chain the content is first versioned and then activated. The
activate command launches the activate workflow.
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
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.
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.
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:
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.