Email Workflow Summary Prerequisites Getting your module ready Create a new module Module dependencies Defining the workflow Create a new process Custom workitems Add workitem Publication steps Process parameters Configure the workflow Workitem handlers Implementing a workitem handler Configuring a workitem handler Test the workflow Define the email workitem handler Update the email workitem handler configuration Update the email workitem handler implementation Mail template configuration Create a freemarker template Configure the template Configure the mailcommand and mailtemplate Summary 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. Prerequisites 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/ Maven: http://maven.apache.org/ 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)
Module creation input example $ mvn archetype:generate -DarchetypeCatalog=https://nexus.magnolia-cms.com/content/groups/public [...] Confirm properties configuration: groupid: org.mydomain.workflow artifactid: mycompany-module-myproject-workflow version: 1.0-SNAPSHOT package: org.mydomain.workflow magnolia-version: 5.4.5 module-class-name: MyProjectWorkflowModule module-name: myproject-workflow Y: Import the module into your IDE Module dependencies 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. mycompany-module-myproject-workflow pom [...] <dependency> <groupid>info.magnolia.workflow</groupid> <artifactid>magnolia-module-workflow-jbpm</artifactid> </dependency> <dependency> <groupid>info.magnolia</groupid> <artifactid>magnolia-module-mail</artifactid> </dependency> [...] In this case I'm letting the parent pom manage the versions. For Magnolia 5.3.7 we are using magnolia-module-workflow-jbpm-5.4.4 and magnoli a-module-mail-5.2.1.
Update your module descriptor located under src/main/resources/meta-inf/magnolia/myproject-workflow.xml. myproject-workflow.xml [...] <dependency> <name>workflow-jbpm</name> <version>5.5/*</version> </dependency> <dependency> <name>mail</name> <version>5.3/*</version> </dependency> [...] Defining the workflow Create a new process 1. Create a new jbpm Process Diagram.
2. Save the MyPublication.bpmn2 file under /src/main/resources. 3. You will now have an empty process file in your module. Custom workitems 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 email and define the parameters used to send the email. MyDefinitions.wid import org.drools.process.core.datatype.impl.type.stringdatatype [ // the Email notification work item [ "name" : "email", "parameters" : [ "subject" : new StringDataType(), "body" : new StringDataType(), "recipient" : new StringDataType() ],
] ] "displayname" : "EmailNotification" Add workitem 1. If your MyPublication.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 email workitem that was defined in the previous step to appear in the Custom Tasks drawer of the modeler's palette. 2. 3. Add the newly added EmailNotification workitem from the palette into your process. Connect the Start Event to the EmailNotification by: a. b. c. hovering over the Start Event. clicking the arrow icon. dragging the arrow to point to the EmailNotification. 4. 5. Add an End Event. Connect the EmailNotification to the End Event. Publication steps To add the publication steps we call Magnolia's Publication process from within our custom process. (This involves a 'Reusable Process' or 'Call Activity' Le arn 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 before the EmailNotifi cation. ( Note: In other versions of Eclipse you may find this under Activities > Call Activity) 2. Double-click the Call Activity to set a Name and Called Activity. info.magnolia.workflow.publication will be the Called Activity at this step. If you are using Magnolia 5.4 then use info.magnolia.workflow.reviewforpublication for the Called Activity. 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. (Note: 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 process variable mgnldata 3. Create variables for taskid and commandname 4. Create a mapping for mgnldata input and output parameters inside the Call Activity.
5. Create additional input mappings for taskid and commandname
6. To access the parameters in our email workitem, create input mappings in the custom email task. First map the subject. 7. 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.
Workitem handlers 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 erface. org.kie.api.runtime.process.workitemhandler int EmailWorkItemHandler.java package org.mydomain.workflow.workitems; import org.kie.api.runtime.process.workitem; import org.kie.api.runtime.process.workitemhandler; import org.kie.api.runtime.process.workitemmanager; public class EmailWorkItemHandler implements WorkItemHandler { private static final Logger log = LoggerFactory.getLogger(EmailWorkItemHandler.class); @Override public void executeworkitem(workitem workitem, WorkItemManager manager) { // read data from our email work items parameters String subject = String.valueOf(workItem.getParameter("subject")); String body = String.valueOf(workItem.getParameter("body")); String recipient = String.valueOf(workItem.getParameter("recipient")); // read data from mgnldata parameter map Map<String, Object> data = (Map<String, Object>) workitem.getparameter("mgnldata"); String path = (String) data.get("path"); body = String.format(body, path); log.warn("sending email to " + recipient); log.warn("subject: " + subject); log.warn("body: " + body); @Override public void abortworkitem(workitem workitem, WorkItemManager manager) {
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. 1. Change the property /modules/workflow/commands/workflow/activate/activate@workflow to point to your workflow. 2. 3. 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. package org.mydomain.workflow.workitems; import info.magnolia.module.workflow.jbpm.workitem.handler.definition.configuredworkitemhandlerdefinition; public class EmailWorkItemHandlerDefinition extends ConfiguredWorkItemHandlerDefinition { private String mailcommand; private String mailtemplate; public EmailWorkItemHandlerDefinition() { setimplementationclass(emailworkitemhandler.class);
public String getmailtemplate() { return mailtemplate; public String getmailcommand() { return mailcommand; public void setmailtemplate(string mailtemplate) { this.mailtemplate = mailtemplate; public void setmailcommand(string mailcommand) { this.mailcommand = mailcommand; 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. package org.mydomain.workflow.workitems; import info.magnolia.commands.commandsmanager; import java.util.hashmap; import java.util.map; import javax.inject.inject; import org.kie.api.runtime.process.workitem; import org.kie.api.runtime.process.workitemhandler; import org.kie.api.runtime.process.workitemmanager; import org.slf4j.logger; import org.slf4j.loggerfactory; public class EmailWorkItemHandler implements WorkItemHandler { private static final Logger log = LoggerFactory.getLogger(EmailWorkItemHandler.class); private static final String TEMPLATE_PARAMETER_NAME= "mailtemplate"; private static final String DATA_PARAMETER_NAME= "mgnldata"; private final EmailWorkItemHandlerDefinition definition; private final CommandsManager commandsmanager; @Inject public EmailWorkItemHandler(EmailWorkItemHandlerDefinition definition, CommandsManager commandsmanager) { this.definition = definition; this.commandsmanager = commandsmanager; @Override public void executeworkitem(workitem workitem, WorkItemManager manager) { Map<String, Object> mailparameters = new HashMap<String, Object>();
mailparameters.put(template_parameter_name, definition.getmailtemplate()); mailparameters.put(data_parameter_name, workitem.getparameter(data_parameter_name)); try { commandsmanager.executecommand(definition.getmailcommand(), mailparameters); catch (Exception e) { log.error("sending email failed.", e); manager.completeworkitem(workitem.getid(), parameters); @Override public void abortworkitem(workitem workitem, WorkItemManager manager) { 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 mgnldata map. <html> <head> My Publication </head> <body> <dl> [#list mgnldata?keys as key] <dt>${key</dt> [#if mgnldata[key]?is_string] <dd>${mgnldata[key]</dd> [#else] <dd>value not a string</dd> [/#if] [/#list] </dl> </body> </html> 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.