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

The templates are currently in the system CMS ([engineDir]/system/cms) and can be modified there directly. The CMS structure is as follows:

#cms_de.yaml
Notification:

  # notification kind
  new-task:

    Templates:

      # 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/mail/Content.html

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

  • ivy.session: ch.ivyteam.ivy.workflow.IWorkflowSession

  • ivy.cm: ch.ivyteam.ivy.cm.exec.ContentManagement

  • ivy.html: only one method ivy.html.escape(..) is available

  • ivy.branding: only one method ivy.branding.ref(..) is available

Note

You need to manually escape untrusted input. 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. Place them in the system CMS and use them in the template via ivy.cm.ref(..).