Sending Notifications

The Notifications add-on can be integrated into BPM to allow sending messages for a user task and service task. Install Notifications and set the jmix.bpm.notification-sending-enabled property to true since it is disabled by default.

jmix.bpm.notification-sending-enabled=true

In the modeler, an additional section will appear for user and service tasks.

The following properties should be set:

Send notifications - a checkbox should be selected to send notifications.
Recipient - a recipient of the notification. For a user task, you can select a task assignee as a recipient or a specific user recorded in a process variable. For a service task, only a specific user can be set as a recipient.
Notification template - a template for the configured notification. Setting templates is described below.

Configuring Templates

Follow the steps to create notification templates:

Create a JSON file containing the following information:

name - a template name that will be displayed in the modeler.
code - a unique template code.
subjectTemplatePath - a path to the template with the notification subject.
bodyTemplatePath - a path to the template with the notification message.
channels - a list of channels used for sending, possible values: in-app and email.

contentType - a content type, possible values: plain and html.

Here is an example:

[
  {
    "name": "Notification for user task",
    "code": "userNotification",
    "subjectTemplatePath": "ntf/default-subject-notification.txt",
    "bodyTemplatePath": "ntf/user-task-body-notification.txt",
    "channels": [
      "in-app",
      "email"
    ],
    "contentType": "html"
  },
  {
    "name": "Notification for service task",
    "code": "serviceNotification",
    "subjectTemplatePath": "ntf/default-subject-notification.txt",
    "bodyTemplatePath": "ntf/service-task-body-notification.txt",
    "channels": [
      "in-app",
      "email"
    ],
    "contentType": "plain"
  }
]

Create files with the subject and body of the notification. The subjectTemplatePath and bodyTemplatePath attributes point to a file with a specific template.

The following placeholders are available at runtime:
- context.executionId - an execution id.
- context.processDefinitionId - an id of the process definition.
- context.processDefinitionName - a name of the proces definition.
- context.processID - an id of the process.
- context.taskId - an id of the task.
- context.TaskName - a name of the task.
- context.recipientUser- a notification recipient. An entity that extends UserDetails.
- context.taskAssigneeUser - a user assigned to the task in case of a user task.
- context.variables - all available process variables that can be accessed in Groovy format, for example, ${context.variables.order.id}.
  
  Here is an example of a template with a notification body for a user task:
  Dear ${context.recipientUser.username}, You email ${context.recipientUser.email} is used to reach needed person. Your subordinate ${context.taskAssigneeUser.username} has one assigned task with name ${context.taskName} and id ${context.taskId}. Please take into account that process ${context.processDefinitionName} is very important for our business practice.
Set the path to the template JSON file in application.properties. The default value is notifications/notification-templates.json.
```
jmix.bpm.notification-templates-path=/ntf/ntf-templates.json
```