Create a new workflow

1. In the project business-workflow-scenarios, right click on the source folder /src/main/resources and click on New > Others...
2. Open the BPMN2 folder and select jBPM Process Diagram. Press next.
3. Fill the information as following:
   
   
   
   
4. The process contains, per default, an untyped start event. We will keep it as it so far.

Define a custom send email work item handler (task)

1. In order to use custom work item handlers in the Eclipse BPMN editor, we need to create 2 files used exclusively at development time.

2. In the /src/main/resources/META-INF, create a file named WorkItemDefinitions.wid and fill it as following:

   WorkItemDefinitions.wid  Expand source

   import org.drools.process.core.datatype.impl.type.StringDataType
    
   [
      //Email notification task
      [
        "name" : "sendEmail",
        "displayName" : "SendEmailNotification"
      ]
   ]

   Good to know

   The name property will be used later on to link the definition with the implementation class.

3. In the /src/main/resources/META-INF, create a file named drools.rulebase.conf and fill it as following:

   drools.rulebase.conf  Expand source

   drools.workDefinitions = WorkItemDefinitions.wid  

4. If the EmailPublicationWorkflow.bpmn2 files is open, close and reopen it.  We should see now a new category called Custom Tasks in the palette. It should contains one task called as the displayName property defined in the WorkItemDefinitions.wid file.

Draw the custom workflow

1. In the BPMN editor, drag and drop the SendEmailNotification task and an End events into the diagram.

2. Link the Start event with the SendEmailNotification task and the SendEmailNotification task with the End event. We should obtain this:
   
   
   
   
3. To extend the default publication workflow, drag and drop a Reusable Process (under Sub Processes folder) between the Start event and the SendEmailNotification task. We should obtain this:
   
   
   
   

4. Click on the Call Activity 1 element, and change the properties as following:
   
   
   
   

   Good to know

   To link to an existing process, we must refer to it thanks to its process id. The default publication process id is info.magnolia.workflow.ReviewForPublication.

5. Still in the element properties panel, open the General tab and change the name to ReviewForPublication. You can set any other meaningful name here.

Set the tasks parameters

1. First, we need to define the java.util.Map type in the process (it's not part of the default types). In the global diagram Properties panel, click on the Definitions tab and press on the + icon. In the dialog box, search for java.util.Map and select it. We should see the following entries in the interface:

   
   
    

2. Let's create the process variables. In the same Properties panel, click on the Data Items tab and open the Local Variable section. Add a process variable called mgnlData type java.util.Map and another called commandName type String. You should obtain the following screen:

   
   
    

3. Map the mgnlData and the commandName variables as input data for the call activity ReviewForPublication. Click on the call activity diagram element, go the Properties panel and open the I/O Parameters tab. Expand the Input Data Mapping section, click on the + icon and map the variable as following:
   
   
   
   
4. Map the mgnlData variable as input data for the task SendEmailNotification. 

Implement the SendEmailNotification task

1. Implement the work item handler definition. We need two String properties storing the mail template name to use to build the email and the command name to execute.

   info.magnolia.services.training.workflow.task.SendEmailNotificationWorkItemHandlerDefinition  Expand source

   /**
    * This file Copyright (c) 2017 Magnolia International
    * Ltd.  (http://www.magnolia-cms.com). All rights reserved.
    *
    *
    * This program and the accompanying materials are made
    * available under the terms of the Magnolia Network Agreement
    * which accompanies this distribution, and is available at
    * http://www.magnolia-cms.com/mna.html
    *
    * Any modifications to this file must keep this entire header
    * intact.
    *
    */
   package info.magnolia.services.training.workflow.task;
   
   import info.magnolia.module.workflow.jbpm.workitem.handler.definition.ConfiguredWorkItemHandlerDefinition;
   
   /**
    * Definition of the task {@link SendEmailNotificationWorkItemHandler}.
    *
    * @author Magnolia International Ltd.
    */
   public class SendEmailNotificationWorkItemHandlerDefinition extends ConfiguredWorkItemHandlerDefinition {
       /** Mail command to use. */
       private String mailCommand;
       /** Mail template to use. */
       private String mailTemplate;
   
       /**
        * Constructor.
        */
       public SendEmailNotificationWorkItemHandlerDefinition() {
           // Assign of the default implementation
           this.setImplementationClass(SendEmailNotificationWorkItemHandler.class);
       }
   
       /**
        * @return the mailCommand
        */
       public String getMailCommand() {
           return this.mailCommand;
       }
   
       /**
        * @param mailCommand
        *            the mailCommand to set
        */
       public void setMailCommand(String mailCommand) {
           this.mailCommand = mailCommand;
       }
   
       /**
        * @return the mailTemplate
        */
       public String getMailTemplate() {
           return this.mailTemplate;
       }
   
       /**
        * @param mailTemplate
        *            the mailTemplate to set
        */
       public void setMailTemplate(String mailTemplate) {
           this.mailTemplate = mailTemplate;
       }
   }

2. Implement the work item handler.

   info.magnolia.services.training.workflow.task.SendEmailNotificationWorkItemHandler  Expand source

   /**
    * This file Copyright (c) 2017 Magnolia International
    * Ltd.  (http://www.magnolia-cms.com). All rights reserved.
    *
    *
    * This program and the accompanying materials are made
    * available under the terms of the Magnolia Network Agreement
    * which accompanies this distribution, and is available at
    * http://www.magnolia-cms.com/mna.html
    *
    * Any modifications to this file must keep this entire header
    * intact.
    *
    */
   package info.magnolia.services.training.workflow.task;
   
   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;
   
   /**
    * Implementation of the send email notification task.
    *
    * @author Magnolia International Ltd.
    */
   public class SendEmailNotificationWorkItemHandler implements WorkItemHandler {
       /** Logger. */
       private static final Logger LOG = LoggerFactory.getLogger(SendEmailNotificationWorkItemHandler.class);
   
       /** Template name parameter. */
       private static final String TEMPLATE_PARAMETER_NAME = "mailTemplate";
       /** Data parameter name. */
       private static final String DATA_PARAMETER_NAME = "mgnlData";
   
       /** The related definition class instance. */
       private final SendEmailNotificationWorkItemHandlerDefinition definition;
       /** The command manager. */
       private final CommandsManager commandsManager;
   
       @Inject
       public SendEmailNotificationWorkItemHandler(final SendEmailNotificationWorkItemHandlerDefinition definition,
               final CommandsManager commandsManager) {
           this.definition = definition;
           this.commandsManager = commandsManager;
       }
   
       @SuppressWarnings("unchecked")
       @Override
       public void executeWorkItem(WorkItem workItem, WorkItemManager manager) {
           // Gets the local variable from process instance
           Map<String, Object> mgnlData = (Map<String, Object>) workItem.getParameter(DATA_PARAMETER_NAME);
   
           // Builds the parameters required to send an email
           Map<String, Object> mailParameters = new HashMap<String, Object>();
           mailParameters.put(TEMPLATE_PARAMETER_NAME, this.definition.getMailTemplate());
           mailParameters.put(DATA_PARAMETER_NAME, mgnlData);
   
           // Executes the send email command
           try {
               this.commandsManager.executeCommand(this.definition.getMailCommand(), mailParameters);
           } catch (Exception e) {
               LOG.error("Sending email failed.", e);
           }
   
           // Marks the task as completed so the process can continue
           manager.completeWorkItem(workItem.getId(), mgnlData);
       }
   
       @Override
       public void abortWorkItem(WorkItem workItem, WorkItemManager manager) {
   
       }
   }

3. Implement the email template.

   /src/main/resources/business-workflow-scenarios/templates/email.ftl  Expand source

   <html>
       <body>
           Publication email notification:
   
           <br>
           <table border="1">
           [#list mgnlData?keys as key]
           <tr>
               <td>${key}</td>
   	        [#if mgnlData[key]?is_string]
   	            <td>${mgnlData[key]}</td>
   	        [#else]
   	            <td>value not a string</td>
   	        [/#if]
           </tr>
           [/#list]
           </table>
       </body>
   </html>

Configure Magnolia

1. Add a new email template definition. Open the config app and browse to the node /modules/mail/config/templatesConfiguration. Create a template called emailNotification and fill it as following:
   
   
   
   

2. Add a new work item handler definition. Still in the config app, browse to the node /modules/business-workflows-scenarios. Create a folder called workItemHandlers and a sub node called sendEmail (same name as the one defined in the the .wid file). Enter the following properties:
   
   
   
   

   Good to know

   The default mail command is called sendMail.
   The mail template property value must be the same as the template node name defined in the previous step.

3. Add a new publication workflow. Still in the config app and in the same node, create a folder called workflows. Enter the following properties.
   
   
   
   
4. Apply the new workflow to the publication command. Still in the config app, browse to the node /modules/workflow/commands/workflow/activate/activate. Set the workflow property value with the name of the workflow node created in the previous step. You should see the following screen:
   
   
   
   
5. Restart your Tomcat server.

Test the workflow

1. Go to the config app and browse to the node /server/activation/subscribers/magnoliaPublic8080. Set the active property to false.
2. Go the pages app and select the page called "Other".
3. Press Publish. Follow the publication procedure. At the end, you should have received an email in your mail box.

Just in case you can't get it working, here are some configs:

config.modules.business-workflows-scenarios.workflows.xmlconfig.modules.business-workflows-scenarios.workItemHandlers.xmlconfig.modules.mail.config.templatesConfiguration.emailNotification.xmlconfig.modules.workflow.commands.workflow.activate.activate.xmlEmailPublicationWorkflow.bpmn2training_settings.xml