18. Workflow Email Patterns

This section explains how to enable automatic email notifications for the 6 common workflow scenarios using Native BPMN Support.

We have updated the system to support "Plug-and-Play" listeners. You do not need to write Java code; just configure your BPMN file as shown below.

1. Email Someone When a Process Starts

Use an Execution Listener on the StartEvent. This sends an email immediately when the workflow begins.

BPMN XML

<startEvent id="start" flowable:initiator="initiator">
    <extensionElements>
        <!-- Native Execution Listener using our universal delegate -->
        <flowable:executionListener event="start" delegateExpression="${sendReminder}">
            <!-- Configure Recipient, Subject, and Body -->
            <flowable:field name="to" stringValue="admin@workingflow.com"/>
            <flowable:field name="subject" stringValue="New Workflow Started"/>
            <flowable:field name="body" expression="Process ${processDefinitionId} started by ${initiator}"/>
        </flowable:executionListener>
    </extensionElements>
</startEvent>

2. Email Someone When a Process Ends

Use an Execution Listener on the EndEvent. This guarantees an email is sent when the process finishes successfully.

BPMN XML

<endEvent id="end">
    <extensionElements>
        <flowable:executionListener event="end" delegateExpression="${sendReminder}">
            <flowable:field name="to" expression="${initiator}"/>
            <flowable:field name="subject" stringValue="Workflow Completed"/>
            <flowable:field name="body" stringValue="Your request has been fully processed."/>
        </flowable:executionListener>
    </extensionElements>
</endEvent>

3. Email When a Task is Assigned or Becomes Available

${taskEmailListener} supports two distinct events for task notification. Choose the right one based on how the task is assigned.

event="create" — Task First Appears (Recommended for most cases)

Fires the moment a task becomes available — whether it has a direct assignee or is open to a candidate group. This is the correct event for role-based tasks because it fires at creation, before anyone claims it.

• For direct assignment tasks: emails the assignee immediately
• For candidate group tasks: emails all members of the role group at the moment the task appears

<!-- Works for direct assignment AND candidate group tasks -->
<userTask id="managerApproval" name="Manager Approval" flowable:candidateGroups="ROLE_MANAGER">
    <extensionElements>
        <flowable:taskListener event="create" delegateExpression="${taskEmailListener}">
            <flowable:field name="subject" stringValue="New Task Available"/>
            <flowable:field name="body" stringValue="A new approval task is waiting for your team."/>
        </flowable:taskListener>
    </extensionElements>
</userTask>

event="assignment" — Task is Claimed or Directly Assigned

Fires when the task assignee is explicitly set — either because the task was directly assigned at creation, or because a user claimed a candidate-pool task.

• For direct assignment tasks: fires at creation (same time as create)
• For candidate group tasks: fires only when a user claims the task — role members are NOT notified when the task first appears

⚠ Do not attach both create and assignment to the same directly-assigned task. Both events fire at task creation for directly assigned tasks, resulting in duplicate emails. Use one or the other.

<!-- Useful for notifying someone when they claim a pooled task -->
<userTask id="reviewTask" name="Document Review" flowable:candidateGroups="ROLE_MANAGER">
    <extensionElements>
        <flowable:taskListener event="assignment" delegateExpression="${taskEmailListener}">
            <flowable:field name="subject" stringValue="Task Claimed"/>
            <flowable:field name="body" stringValue="You have claimed this task. Please complete it promptly."/>
        </flowable:taskListener>
    </extensionElements>
</userTask>

4. Email When a Task is Completed

Use a Task Listener with event="complete". This is useful for notifying the process initiator, a manager, or any other party that a step is done.

The to field is required for complete events. If to is missing or the specified email does not belong to a registered user in the system, the notification is skipped and the failure is logged to Error Logs (the task completion itself is NOT affected).

<userTask id="reviewTask" name="Review Documents">
    <extensionElements>
        <!-- Triggers when the user clicks Complete -->
        <flowable:taskListener event="complete" delegateExpression="${taskEmailListener}">
            <!-- Required: who to notify. Use an expression to reference a process variable. -->
            <flowable:field name="to" expression="${initiator}"/>
            <flowable:field name="subject" stringValue="Review Finished"/>
            <flowable:field name="body" stringValue="The manager has completed the review."/>
        </flowable:taskListener>
    </extensionElements>
</userTask>

Validation: The to field is evaluated at runtime. If it contains an email that is not registered in the system, a warning is logged to the Error Logs screen and the email is silently skipped. The task completion is never blocked.

5. Emailing a Role (Group)

You can send emails to all users with a specific Role (e.g., ROLE_MANAGER).

Method A: Process Start/End (Execution Listener) Use the toRole field in ${sendReminder}.

<flowable:executionListener event="start" delegateExpression="${sendReminder}">
    <!-- Emails everyone with ROLE_MANAGER -->
    <flowable:field name="toRole" stringValue="ROLE_MANAGER"/>
    <flowable:field name="subject" stringValue="Attention Managers"/>
    <flowable:field name="body" stringValue="A new high-priority process has started."/>
</flowable:executionListener>

Method B: Task Assignment (Candidate Groups) If you assign a task to a Candidate Group, use event="create" to notify all group members the moment the task appears.

⚠ Important: Use event="create", NOT event="assignment". The assignment event only fires when someone claims the task — role members would receive no notification when the task first becomes available.

<userTask id="groupTask" name="Group Review" flowable:candidateGroups="ROLE_MANAGER">
    <!-- 'create' fires when the task first appears — before anyone claims it -->
    <flowable:taskListener event="create" delegateExpression="${taskEmailListener}">
        <flowable:field name="subject" stringValue="New Pooled Task"/>
        <flowable:field name="body" stringValue="A new task is available for the Manager team to claim."/>
    </flowable:taskListener>
</userTask>

6. Dynamic Recipient Selection

You can let users choose who gets the email by using a Process Variable which is selected in a previous User Task form.

Step 1: User Selects Recipient In a previous User Task form, use a dropdown content field to save the selected person's email to a variable, e.g., targetUserEmail.

Step 2: Use Variable in BPMN Reference that variable in the to field expression.

<serviceTask id="sendDynamicEmail" flowable:delegateExpression="${sendReminder}">
    <extensionElements>
        <!-- Uses the variable 'targetUserEmail' set in previous form -->
        <flowable:field name="to" expression="${targetUserEmail}"/>
        <flowable:field name="subject" stringValue="You were selected"/>
        <flowable:field name="body" stringValue="The previous user chose you for this step."/>
    </extensionElements>
</serviceTask>

What the Recipient Sees

Every reminder email is sent as a branded HTML email (in production). It includes:

The language of the labels ("Process", "Task", "Message", footer text) is controlled by the system language setting in Admin → System Settings.

In development (default profile), the DemoEmailService logs all fields to the console instead of sending a real email, including the process name, task name, and body.