Community Wiki
Page tree
Skip to end of metadata
  • Created on 2016-12-01, last edited by Richard Gange on 2019-07-29
Go to start of metadata

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.

  2. Define a local process variable mgnlData.

  3. Create local process variables for taskId, commandName, and 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, and commandName.
  4. Create an mgnlData input mapping for the Reject Notification Task.

Sequence flow

In this particular workflow we have interaction from someone on the legal team. This interaction represents a choice taken in whether or not to push the item through to the next step. If the item is approved it either moves on to another approval step handled by another workflow. On the other hand if the item gets rejected then 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 these possible paths.

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 your custom module.

Here I've registered the sixEyeReviewForPublication workflow within my 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. Create a folder in your custom module named tasks.
  2. In the tasks folder create a node named legal.
  3. Add a property to the legal node named extends with a value of /modules/workflow-jbpm/tasks/publish.
  4. Add a node under the legal node named groups. 
  5. Add a property to the groups node named extends with a value of override.
  6. Add a property to the groups node named legal with a value of legal. (I'm making the assumption that there is a group called "legal" configured in Security )

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

Now you test your workflow configuration and make sure everything is in place correctly.

Change the property /modules/workflow/commands/workflow/activate/activate@workflow to point to your workflow. Also, don't forget to assign someone (superuser) to the legal group.

Final Configuration

During the testing of the workflow you may have noticed a few labels that need to be updated. Remember for simplicity sake we reused the publish task definition by extending it. In some cases we will see that some of the keys for labels will be different since the name of the task is legal. For example, when we see the list of tasks in the pulse.

First of all, what's happening here is that the system expects to find a label for title using the key tasks.legal.title. However, if the system doesn't locate that key then it will simply display the key where it expects to find that value. A quick fix for this would be to simply add a title node as a child of the legal task defined here /modules/myproject-workflow/tasks/legal. Then add a property to the title node named label with a value of Legal Review Requested.

This is an ok solution in the case you don't need to worry about this label being translated. Everyone who uses the system is also using the same language, which is this case a lot of the time. However, if your company spans more than one country where users may be using the system in different languages then you need a more flexible solution. This involves Making a module translatable which is a bit beyond the scope of this tutorial.

If we open up the legal task we will see another missing label. In this case tasks.legal.publicationTitle.

You can fix this label using the same approach I discussed above. Either create it directly in the config or use the best practice approach of using properties files. You may also want to consider creating a Message view definition for your legal task. Remember we reused the publish task by extending it so we are using the messageView created for the publish task. For example, you may want to change the label Approve & Publish to Approve since publishing doesn't happen until the publishing group gives the go ahead. Or maybe you need to add some custom actions for the legal group.

  • No labels