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.

Visual representation of a process

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

workflows

required

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

     <workflow-name>

required

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

         id

required

Used for identifying processes inside jBPM.

         name

required

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

         resourcePath

required

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

         type

required

Magnolia currently only loads processes of type bpmn.

         definition

optional

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.

Commands 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 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.

Property Description

commandName

required

The name of the command to be called upon acceptance from the reviewer.

enabled

optional, default is true

Enabled or disable the configuration.

parameterMapName

required

The name of the map object to be sent to the workflow. See Input and output parameters section.

path

optional, default is /

Map the process to a path.

repository

optional, default is website

Map the process to a path.

workflow

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.

Example configuration

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

enabled

optional, default is true

Enabled or disable the configuration.

path

optional, default is /

Map the process to a path.

workflow

required

The name of the workflow to be called.

Name of the workflow configuration

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:

parameterMapName in configuration

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

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.

Feedback

DX Core

×

Location

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