Page tree
Skip to end of metadata
Go to start of metadata

The tutorial has become out-of-date. The screenshots do not always reflect what you might see. This depends in which versions of Eclipse you use and which plugin version is installed. You can still use these instructions as a rough guide of how the plugin works and how to create workflows. However, I would recommend you start any new custom workflow project with one of our existing bpmn2 files located in the Git repository. You might even find that the Eclipse plugin simply doesn't produce "valid" workflows. In these cases I modify the XML directly or use an online tool.

For those simply wanting a six eye workflow you can find Six Eye Workflow module in the incubator. 

Summary

This tutorial shows the steps necessary to create a six-eye workflow in Magnolia 5. For this example we will assume that the legal department must approve all new content published as well as the publishing group. So we will have an editor which provides the first set of eyes, someone from the legal group providing the second set of eyes, and finally someone from the publishing group to provide the third set of eyes in this workflow. Some of the detail has been left off this tutorial since it was covered in Email Workflow.

If you have any problems with this tutorial please comment at the bottom.

Prerequisites

Getting your module ready

Defining the workflow

Create a new process

  1. Create a new jBPM Process Diagram called SixEyeReviewForPublication.bpmn2 under /src/main/resources.

Legal review user task

  1. In the Tasks drawer of the modeler's palette you will find the User Task.
  2. Drag a User Task from the palette into the workflow and set the Name to Legal Review. (Double-click the User Task to bring up the Properties dialog.)
  3. Set the Task Name to legal. (I also cleared out all the other fields.)

    The pencil button is used to edit the fields.

  4. Since legal will make a decision about whether or not the item should be approved we need to model this. Using a diverging exclusive gateway we can create alternative paths within a process flow. For a given instance of the process, only one of the paths can be taken. In the Gateways drawer of the modeler's palette you will find the Data-based Exclusive (XOR) gateway.
  5. Drag a Data-based Exclusive (XOR) gateway into the workflow and set its Gateway Direction to Diverging.
  6. Connect the Start Event to the Legal Review User Task by:
    1. hovering over the Start Event
    2. clicking and holding the arrow icon
    3. dragging the arrow to point to the Legal Review User Task
  7. Connect the Legal Review User Task to the Data-based Exclusive (XOR) gateway.

Reusable Process

To add the the next set of eyes and publication steps we call Magnolia's OOTB four-eye Review for Publication process from within our custom process. (This involves a 'Reusable Process' or 'Call Activity' Learn more). Because we are targeting the jBPM runtime we do not need to explicitly import our process definition from the external file. Just add the process ID to the Called Activity field of the Call Activity. The jBPM runtime will resolve the IDs at runtime or throw a runtime exception if the called process is not available.

  1. Under the Sub Processes drawer you will find a Reusable Process. Drag the Reusable Process into your process after the second Data-based Exclusive (XOR) gateway.
  2. Add an End Event.
  3. Double-click the Call Activity to set a Name and Called Element. In this case, info.magnolia.workflow.ReviewForPublication will be the Called Element.
  4. Connect the Call Activity and the End Event to the rest of the workflow.

Reject notification

The legal department and the publishing group both have the choice to reject the item. In the event they do reject the item we need to send a notification to the pulse to inform the editor that the item has been rejected. For this we will use a Custom Task. This Custom Task will make use of an already defined workItem in the workflow-jbpm module.

To create custom workitems you have to create two files inside the META-INF folder of your project.

The two files are not used at runtime, but are necessary for modeling your process.

  1. drools.rulebase.conf file contains a drools.workDefinitions property which points to a space-separated list of workItem definition file.

    drools.rulebase.conf
    drools.workDefinitions = MyDefinitions.wid
  2. Inside the *.wid files is where you define your workItems. In this case we create a workItem rejectNotification.

    MyDefinitions.wid
    import org.drools.process.core.datatype.impl.type.StringDataType
    [
      // the Reject Notification notification work item
      [
        "name" : "rejectNotification",
        "displayName" : "Reject Notification"
      ]
    ]
  3. If your SixEyeReviewForPublication.bpmn2 file was open when you added the drools.rulebase.conf and MyDefinitions.wid files then close it and reopen it. This should trigger the rejectNotification workitem that was defined in the previous step to appear in the Custom Tasks drawer of the modeler's palette.
  4. Add a Reject Notification workItem from the palette into your process.
  5. Add an End Event to the process.
  6. Connect the Reject Notification and the End Event to the rest of the process.

Define process parameters

Magnolia's standard publication process depends on parameters aggregated from various steps before the workflow starts. These parameters hold a map identified as mgnlData. To ensure that these parameters are properly passed to the publication process you need to set input and output parameters.

To access the  mgnlData map throughout the process, define a variable and add a type import at the process level.

  1. Add an import for our parameters map. Click on the process background and select the Properties tab from the bottom window. Click Definitions from the side menu of the Properties tab. Expand Imports and add java.util.Map using the green plus button.

    If the Properties tab doesn't show when you click the process background then enable it through the Window menu of Eclipse.

    The latest versions of the plugin have a slightly different look. This is now found under the Import List section. Click the plus button and add a Java Import Type.

  2. Define a local process variable  mgnlData.

    Now found under Properties List for Process.


  3. Create local process variables for:
    • taskId
    • commandName
    • taskResult

Configure process parameters

Now that we have the process variables defined for the workflow we need to configure each task and activity to use them. 

  1. Create a mapping for the mgnlData input parameter inside the Legal Review User Task.

  2. Create additional input and output mappings for taskResult and create an output mapping for taskId.

  3. Create input mappings for the ReviewForPublication Call Activity which include:
    • mgnlData
    • taskId
    • taskResult
    • commandName.
  4. Create an input mappings for the Reject Notification Task which include:
    • mgnlData
    • taskResult

Sequence flow

We have interaction (i.e. a human task) from someone on the legal team. This interaction represents a choice taken about the workitem. If the item is approved it moves on to another approval step handled by another workflow. On the other hand, if the item gets rejected a reject notification is sent. There is also the possibility to simply abort the workflow altogether.

We need to model in the workflow the sequence flow which reflects all these possible paths. Abort, Approve or Reject.

Double click on the line connecting the gateway to the activity, task, or event to edit the sequence flow. Perform all nine steps that follow.

  1. Name the Sequence Flow coming from the first Data-based Exclusive (XOR) gateway into the ReviewForPublication Call Activity → Approve.
  2. Add Condition with the Conditional Language set to Java.
  3. In the Constraint field add the following code:

    Approve
    Map data = (Map) kcontext.getVariable("taskResult");
    String decision = (String) data.get("decision");
    return "approve".equalsIgnoreCase(decision);
  4. Name the Sequence Flow coming from the the Data-based Exclusive (XOR) gateway into the Reject Notification Task → Reject.
  5. Add Condition with the Conditional Language set to Java.
  6. In the Constraint field add the following code:

    Reject
    Map data = (Map) kcontext.getVariable("taskResult");
    String decision = (String) data.get("decision");
    return "reject".equalsIgnoreCase(decision);
  7. Name the Sequence Flow coming from the the Data-based Exclusive (XOR) gateway directly into the End Event → Abort

  8. Add Condition with the Conditional Language set to Java.

  9. In the Constraint field add the following code:

    Abort
    Map data = (Map) kcontext.getVariable("taskResult");
    String decision = (String) data.get("decision");
    return "abort".equalsIgnoreCase(decision);

Configure the workflow

Configuring the workflow is done by registering a workflows folder in the resources section of your custom module. 

User Tasks

This workflow involves tasks that need to be executed by human actors. A User Task represents an atomic task to be executed by a human actor.

Define the legal review user task

For simplicity sake we will simply extend the publish user task and override a couple things.

  1. From the Configuration app, create a similar configuration as shown in this screenshot. 

    Here is an export: config.modules.workflow-six-eye.tasks.legal.yaml

Reuse the publish user task

For this user task we really don't need to do anything. When we added the task to the workflow we set the Task Name to publish. This will use the publish task which is already defined in the module workflow-jbpm.

Testing the workflow

Update the activate command which calls the workflow. This command is found in the workflow module. In this case it's configured to point to the YAML file created earlier.

 Make sure to assign someone (superuser) to the legal group.

Internationalization

The newly created legal task needs labels for the message view of the Pulse. Create a properties file to hold the keys and values. See Making a module translatable.

module-workflow-six-eye-messages_en.properties
tasks.tasks.title = Publication preview
tasks.tasks.publicationTitle = Publication preview for {1} {2}
  • No labels