Workflow processes
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.
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| Property | Description |
|---|---|
|
required The folder which contains a list of workflow definitions. The name of
the folder must be |
|
required The name of the workflow. The name is arbitrary but must be unique. |
|
required Used for identifying processes inside jBPM. |
|
required The name used in Magnolia to identify the process. This is called from your command launching the workflow. |
|
required Path to the .bpmn file inside your module’s resource directory. |
|
required Magnolia currently only loads processes of type |
|
optional Instead of using the resource path you can use the XML definition
directly. This will override the |
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.
Commands
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 theworkflowworkspace. -
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.
| Property | Description |
|---|---|
|
required The name of the command to be called upon acceptance from the reviewer. |
|
optional, default is true Enabled or disable the configuration. |
|
required The name of the map object to be sent to the workflow. See Input and output parameters section. |
|
optional, default is / Map the process to a path. |
|
optional, default is website Map the process to a path. |
|
required The name of the workflow to be called. |
Example configuration
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
Publishing 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 there is a mappings node defined the mappings are checked first.
If no mapping is found the default configuration is used.
| Property | Description | ||
|---|---|---|---|
|
optional, default is true Enabled or disable the configuration. |
||
|
optional, default is / Map the process to a path. |
||
|
required The name of the workflow to be called.
|
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.
Tutorial
We have put together a step-by-step tutorial on how to create, load and launch custom process.