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:

  1. 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"
  }
]

  2. 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.

  3. 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