Email Notifications

Notifications functionality monitors processes based on defined rules and automatically send email messages to defined recipients, for example when there are deviations in the process flow requiring corrective actions. Notification rules are defined for models, and each model can contain several notification rules. When working with the notifications, the notification rules are first defined, including criteria for sending the email and message contents. When notification rules are in place, the sending of the notifications need to be scheduled using a script (alternatively users can initiate the sending in the UI).

When notifications are processed and sent, the following logic is applied, when dimensions are not used:

1. If the optional filter is defined, it's applied to the model data. If there is no filter, the entire model data is used.
2. If the email subject or body needs to contain dynamically changing information, measures can be defined and used them in the email properties.
3. Criteria defining for example a threshold value, is applied and based on it actual notification email is either sent or not. Measures can be used in the criteria expression (as variables by their names).

When dimensions are used, the logic is as follows:

1. If the optional filter is defined, it's applied to the model data. If there is no filter, the entire model data is used.
2. If notifications are to be sent to several recipients with different message for each recipient, the data can be divided into dimensions (notifications will be sent for each of the dimension values). If no dimensions is defined, maximum of one email message is sent.
3. If the email subject or body needs to contain dynamically changing information, measures can be defined and used them in the email properties. The measures are calculated for each of the dimension values.
4. Criteria defining for example a threshold value, is applied for each of the dimension value (i.e. a potential notification), and based on it actual notification email is either sent or not. Dimensions and measures can be used in the criteria expression (as variables by their names).

Defining notification rules

Notification rules can be defined in Email notifications dialog, that can be opened in the models list by selecting Notifications. The dialog contains a table of all notification rules in the model, and there notifications can be created, edited, deleted and sent. Defining notifications requires at least project Designer or project Administrator permissions (GenericWrite permission).

Notification rules can be double-clicked or select a row and click the Edit button, to open a dialog for editing a notification rule. Each notification rule have following properties:

• Name: Name for the notification rule describing it shortly and identifying it in the model notifications list.
• To, Cc, Bcc: List of to, cc and bcc recipient addresses for the email message. At least one email address needs to be defined in any of the fields. One address is mandatory.
• Subject: Subject of the email message. Cannot be empty.
• Body: Body of the email message. The body can be defined as an html document, if the Message is html is checked.
• Model filter: This filter is applied to the model data, creating the dataset to be used for the notification calculation. The filter can be used to narrow down the data related to which to send the notifications to.
• Measures: Measures are calculated for each of the dimension value (or the entire data, if no dimensions are defined). Measures can be used in the email fields and in the criteria expression.
• Criteria: Expression that determines whether the email is sent or not. For example, the criteria can be used to define that the notification is sent only if a measure is greater than the defined threshold value. The criteria expression is optional, and if not defined, the notification is always sent.
• Message is html: When selected, the email body is interpreted as an html document. If unselected, the email body should contain plain text.
• Priority: Priority of the email message: High, Normal or Low.
• From email address: Email address where the notification appears to be coming from. If there is a default from address defined for the system (SmtpFromAddress), this field can be left empty.
• Reply to addresses: One or several email addresses which appear as recipients when replying to the notification email.
• Dimensions: Dimensions can be used if the defined notification needs to send several emails to different recipients (for example, related to each region, product, customer or other attribute). If no dimensions are defined, one notification email is sent related to the defined notification.

To add dynamic content to the fields defining the email message (e.g. To, Cc, Bcc, Subject, Body), the measure and dimensions names can be used with syntax ${name}. It's also possible to define expressions in the same curly brackets, e.g. ${name.Substring(0,20)}.

Example for email subject (assuming there is a measure numberOfCases):

Process is blocked for total of ${numberOfCases} orders

Another example where there is an embedded expression using the ${...} syntax:

Process is blocked for total of ${Count(EventLog.Cases)} orders

Sending notifications

Notifications can be processed and sent either in the Email notifications dialog by clicking the Send notifications button, or by using the Model.TriggerNotifications() function in the expression language. Note that no actual emails might necessarily be sent if the the criteria for sending the emails is not fulfilled. Note also that triggering the notifications only starts the processing, so neither the Send notifications button nor the TriggerNotifications return any errors if the notification processing fails.

Notifications can be sent from SQL scripts as follows (notifications Notification 1 and Notification 2 for model id 123):

(SELECT 'AnalysisType', '33') UNION ALL
(SELECT 'ContextType', 'Generic') UNION ALL
(SELECT 'Configuration', '{"Root":"ModelById(123).TriggerNotifications([""Notification 1"", ""Notification 2""])"}')
--#GetAnalysis

Setup walkthrough

Let's define a notification which is sent if a certain case attribute value occurs in a case.

1. Open the Notifications rules dialog for a model and click Add notification rule.
2. In the General tab, define a name for the notification rule and a To address.
3. In the Measures tab, click the plus button and define a measure name notifiedCases.
4. Select Cases with specific case attribute value, select a case attribute and a value.
5. In the General tab, define a Subject with following content: There are ${notifiedCases} cases requiring actions!.
6. Go to the Preview emails tab to see how the email contents is created.
7. Define a body text for the email message. You can either use plain text or an html document. When using plain text, uncheck the Message is html checkbox in the Advanced tab.
8. Now the email is sent always when this notification rule is triggered. To define a criteria for the sending, go to the Sending criteria tab and add criteria notifiedCases > 10. This criteria means that the notification is only sent when there are more than 10 cases having that case attribute value. You can check from the Preview emails tab, that if the criteria is not fulfilled, no email is sent.
9. You can then define a filter, if you want to send the notification only related to certain regions data or any other case attribute value. To do this, go to the Model filters tab and add a filter rule.
10. To send several emails related to this notification rule, go to the Advanced tab and add a dimension (e.g. select a case attribute).
11. Go to the Preview emails tab and see that there is a table where there is a row for each email to be sent (each case attribute value.
12. You can also add the dimension value to the email message body (to identify which value the message is related to) with syntax ${dimensionName}. Again go the the Preview emails tab, to see the generated emails messages.