Notification

The Axon Ivy Engine sends notifications to users via different notification channels based on subscription management.

A notification arises from a specific event while the Axon Ivy Engine is running. For example, a task assignment to a user is such an event. A notification can be sent to a specific user or role. In the case of a role, the user candidates are calculated, which means all users of this role. If a user is absent and has substitutes, the substitutes also receive a notification. Which notifications have been sent to which users can be monitored in the engine cockpit.

Notification Channel

A notification will be delivered over a notification channel. The Axon Ivy Engine comes with three built-in channels:

Web Channel: Notifications will be shown in the header section of the Axon Ivy Portal.
Mail Channel: Notifications will be sent as mail.
Microsoft Teams Channel: Notifications will be delivered as Microsoft Teams messages.

Each of these channels can be configured in ivy.yaml. There are also dedicated views in the engine cockpit.

Subscription Management

You can define the default subscriptions for each channel and security system. For example, you can define that by default all users receive notifications for new task assignments over the mail channel but not over the Microsoft Teams channel.

# ivy.yaml
SecuritySystems:
  default:
    Notification:
      Channels:
        mail:
          Enabled: true
          Kinds:
          - new-task
        microsoft-teams:
          Enabled: true
          AllKinds: disabled

All users can override the default subscription settings in their profile in the Axon Ivy Portal.

Note

You can suppress a notification for a task assignment in the process itself. No matter how the subscription is configured, no notification will be created for this given task.

Templating

The content of the notification is templated-based. Based on the given channel there are one or multiple templates for one given notification.

For example, the mail channel always needs a Subject and a Content template. It is the same for all channels either Subject or Content or both are used:

Web Channel: Subject
Mail Channel: Subject, Content
Microsoft Teams Channel: Content

Resolution

Templates are resolved at runtime as follows:

Defined template on the task element from the project CMS:

/Notification/[event]/Templates/[template]/[channel]/Subject|Content

e.g. /Notification/new-task/Templates/my-template/mail/Subject
Defined template on the task element from the system CMS:

/Notification/[event]/Templates/[template]/[channel]/Subject|Content

e.g. /Notification/new-task/Templates/my-template/mail/Subject
Default template from the project CMS:

/Notification/[event]/Templates/Default/[channel]/Subject|Content

e.g. /Notification/new-task/Templates/Default/mail/Subject
Default template from the system CMS:

/Notification/[event]/Templates/Default/[channel]/Subject|Content

e.g. /Notification/new-task/Templates/Default/mail/Subject
Axon Ivy Engine Fallback

CMS Structure

The system CMS is in ([engineDir]/system/cms). Here is an example CMS with a Default template for the mail channel.

#cms_de.yaml
Notification:

  # notification kind
  new-task:

    Templates:

      # template name
      Default:

        # channel
        mail:

          # mail channel needs a subject
          Subject: New Task '<%= ivy.html.escape(ivy.task.name) %>' for <%= ivy.html.escape(ivy.task.activator().displayName()) %>

          # mail channel needs a content
          Content: Hello <%= ivy.session.getSessionUser().getFullName() %><br/>You have this new task: <%= ivy.html.escape(ivy.task.name) %> that has been assigned to: <%= ivy.html.escape(ivy.task.activator().displayName())%>
          # A big template can be placed in an own file
          # here: [engineDir]/system/cms/Notification/new-task/Templates/Default/mail/Content.html

Dynamic Macros

You can use ivy macros and the following variables in templates:

receiver: The receiver of the notification.
payload: The object that was provided as a payload of the notification.
ivy.session: IWorkflowSession with the receiver as session user.
ivy.cm: ContentManagement
ivy.application: IApplication
ivy.html: only one method ivy.html.escape(..) is available
ivy.branding: only one method ivy.branding.ref(..) is available

Note

You need to escape untrusted input manually. For example, a task name can consist of user input. The user input must be properly escaped so that nobody can make XSS or phishing attacks. Use ivy.html.escape() for this.

Resource attachments like images or documents can be used too. Please place them in the system CMS and use them in the template via ivy.cm.ref(..).

Business Notifications

Business notifications can be sent programmatically from a process using the public BusinessNotification API. You can provide the notification receivers and the message programmatically. The message can be a simple String or a multi-lingual message resolved from the CMS.

For more complex use cases a template and payload can be specified. In the template you can use the variable described in the templating chapter and additionally the following variables:

message: String with the provided message in the current language if provided by the CMS.
ivy.task: The current ITask that was active when the notification was sent.
ivy.case: The current ICase that was active when the notification was sent.