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
: ContentManagementivy.application
: IApplicationivy.html
: only one methodivy.html.escape(..)
is availableivy.branding
: only one methodivy.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: