This tutorial shows how to create a simple email workflow in Magnolia 5.3.x or 5.4.x or 5.5.x with Eclipse Luna.
If you have any problems with this tutorial please comment at the bottom.
Magnolia EE 5.3.x or 5.4.x or 5.5.x
Workflow is an enterprise edtion feature.
- Eclipse Luna Service Release 1 (4.4.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.1.5) for Eclipse (or similar): http://eclipse.org/bpmn2-modeler/
- Git: http://git.magnolia-cms.com/gitweb/
Getting your module ready
Create a new module
Set up your module with Maven and use archetype:
magnolia-module-archetype (An archetype to create basic Magnolia modules)
Import the module into your IDE
Ensure that the pom file contains all of the necessary dependencies. As workflow is part of the Enterprise Edition, un-comment the repository at the end of the file.
In this case I'm letting the parent pom manage the versions. For Magnolia 5.3.7 we are using
Update your module descriptor located under
Defining the workflow
Create a new process
- Create a new jBPM Process Diagram.
- Save the MyPublication.bpmn2 file under
- You will now have an empty process file in your 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.conffile contains a
drools.workDefinitionsproperty which points to a space-separated list of workItem definition file.
*.widfiles is where you define your workItems. In this case we create a workItem
If your MyPublication.bpmn2 file was open when you added the
MyDefinitions.widfiles then close it and reopen it. This should trigger the
- Add the newly added
EmailNotificationworkItem from the palette into your process.
Start Eventto the
- hovering over the
- clicking the arrow icon.
- dragging the arrow to point to the
- hovering over the
- Add an
- Connect the
To add the publication steps we call Magnolia's 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 the
Reusable Processinto your process before the
EmailNotification. (Note: In other versions of Eclipse you may find this under Activities –>
Call Activityto set a Name and Called Activity.
info.magnolia.workflow.Publicationwill be the Called Activity at this step.
If you are using Magnolia 5.4 then use
info.magnolia.workflow.ReviewForPublicationfor the Called Activity.
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.Mapusing the green plus button. (Note: If the Properties tab doesn't show when you click the process background then enable it through the Window menu of Eclipse)
- Define a process variable
- Create variables for
Create a mapping for
mgnlDatainput and output parameters inside the
- Create additional input mappings for
- To access the parameters in our email workitem, create input mappings in the custom email task. First map the subject.
- Map the remaining parameters body, recipient, and mgnlData.
Configure the workflow
Configuring the workflow is done by registering a workflows folder in your custom module.
Here I've registered the myPublication workflow within my custom module.
When you have customized your workflow, the next step is to integrate the workflow design into your project. This is achieved using workItemHandlers.
Implementing a workitem handler
A workItemHandler takes care of executing or aborting workItems. Start by implementing the
Configuring a workitem handler
Configuring the workItemHandler is done by registering a workItemHandlers folder in your custom module.
Here I've registered my email workItemHandler within my custom module myproject-workflow.
Test 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.
- Set up a subscriber configuration to point to a test public instance.
- Activate a page from the pages app and verify in the log that you see a successful activation and the log messages from the email workItemHandler.
Define the email workitem handler
Create an email workitem handler definition that will allow for configuration of the mail template and the command to be used when sending the mail.
Update the email workitem handler configuration
Update the configuration to use the new definition class.
Update the email workitem handler implementation
Now that we have a definition class we can get the configured template and command for use in the workitem handler implementation.
Mail template configuration
Create a freemarker template
Create a Freemarker template in your module's class path. (For example in
src/main/resources/myproject-workflow/email/myPublication.ftl). The template will dump the whole
Configure the template
Configure the template within the mail module.
Configure the mailCommand and mailTemplate
Create properties for the mailCommand and mailTemplate on the email workItemHandler definition.