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
Magnolia EE 5
Workflow is an enterprise edition feature.
- Eclipse Neon.1a Release (4.6.1). You are free to work with an IDE of your choice. However, for this particular implementation we recommend working with Eclipse to ensure that that implementation is successful. See Working with Eclipse and Git .
- BPMN modeler plugin (1.3) for Eclipse (or similar): http://eclipse.org/bpmn2-modeler/
- Maven: http://maven.apache.org/
- Git: http://git.magnolia-cms.com/gitweb/
Getting your module ready
- Please see the steps from Email Workflow - Getting your module ready for completing this section.
Defining the workflow
Create a new process
- Create a new jBPM Process Diagram called SixEyeReviewForPublication.bpmn2 under
/src/main/resources
.
Legal review user task
- In the Tasks drawer of the modeler's palette you will find the
User Task
. - Drag a
User Task
from the palette into the workflow and set the Name to Legal Review. (Double-click theUser Task
to bring up the Properties dialog.) Set the Task Name to legal. (I also cleared out all the other fields.)
The pencil button is used to edit the fields.
- 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. - Drag a
Data-based Exclusive (XOR)
gateway into the workflow and set its Gateway Direction to Diverging. - Connect the
Start Event
to the Legal ReviewUser Task
by:- hovering over the
Start Event
- clicking and holding the arrow icon
- dragging the arrow to point to the Legal Review
User Task
- hovering over the
- Connect the Legal Review
User Task
to theData-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.
- Under the Sub Processes drawer you will find a
Reusable Process
. Drag theReusable Process
into your process after the secondData-based Exclusive (XOR)
gateway. - Add an
End Event
. - Double-click the
Call Activity
to set a Name and Called Element. In this case,info.magnolia.workflow.ReviewForPublication
will be the Called Element. - Connect the
Call Activity
and theEnd 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.
drools.rulebase.conf
file contains adrools.workDefinitions
property which points to a space-separated list of workItem definition file.drools.rulebase.confdrools.workDefinitions = MyDefinitions.wid
Inside the
*.wid
files is where you define your workItems. In this case we create a workItemrejectNotification
.MyDefinitions.widimport org.drools.process.core.datatype.impl.type.StringDataType
[
// the
Reject Notification
notification work item[
"name" : "rejectNotification",
"displayName" : "Reject Notification"
]
]
- If your SixEyeReviewForPublication.bpmn2 file was open when you added the
drools.rulebase.conf
andMyDefinitions.wid
files then close it and reopen it. This should trigger therejectNotification
workitem that was defined in the previous step to appear in the Custom Tasks drawer of the modeler's palette. - Add a
Reject Notification
workItem from the palette into your process. - Add an
End Event
to the process. - Connect the
Reject Notification
and theEnd 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.
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.
- Define a local process variable
mgnlData
. - Create local process variables for
taskId
,commandName
, andtaskResult
.
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.
- Create a mapping for the
mgnlData
input parameter inside the Legal ReviewUser Task
. - Create additional input and output mappings for
taskResult
and create an output mapping fortaskId
. - Create input mappings for the ReviewForPublication
Call Activity
which includemgnlData
,taskId
, andcommandName
. - Create an
mgnlData
input mapping for the Reject NotificationTask
.
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.
- Name the
Sequence Flow
coming from the firstData-based Exclusive (XOR)
gateway into theReviewForPublication
Approve.Call Activity
- Add Condition with the Conditional Language set to Java.
In the Constraint field add the following code:
ApproveMap data = (Map) kcontext.getVariable("taskResult"); String decision = (String) data.get("decision"); return "approve".equalsIgnoreCase(decision);
- Name the
Sequence Flow
coming from the theData-based Exclusive (XOR)
gateway into the Reject NotificationTask
Reject. - Add Condition with the Conditional Language set to Java.
In the Constraint field add the following code:
RejectMap data = (Map) kcontext.getVariable("taskResult"); String decision = (String) data.get("decision"); return "reject".equalsIgnoreCase(decision);
Name the
Sequence Flow
coming from the theData-based Exclusive (XOR)
gateway directly into theEnd Event
AbortAdd Condition with the Conditional Language set to Java.
In the Constraint field add the following code:
AbortMap 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.
- Create a folder in your custom module named tasks.
- In the tasks folder create a node named legal.
- Add a property to the legal node named extends with a value of /modules/workflow-jbpm/tasks/publish.
- Add a node under the legal node named groups.
- Add a property to the groups node named extends with a value of override.
- 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.