This provides a quick reference to the main configuration tasks for the notification manager. You must be signed in as the account holder user to maintain the notification manager.
Getting started
Install the notification manager module, connect it to the process client, and add a notification handler that points to the notification manager. See Installation for instructions.
Default rules
In the portal, to go Settings and then choose System settings to see the system settings. Click on Account manager, and then click on the Notification manager instance link in account manager. This should open in a workbench view in a new tab or window.
Navigate to Notifcation rules, then open the default rules. It will look like this.
[
{
"match": {
"recipient": true
},
"outcome": "medium",
"end": true
}
]
This means "for every notification with a recipient, send it with medium priority, and do not process any more rules".
Outcomes
The different types of outcome are in the Notification outcomes node. Each outcome describes a logically different outcome. There are four pre-set outcomes:
- high – send email immediately
- medium – batch emails and send within 15 minutes
- low – batch emails and send within 240 minutes
- log – log the notification
Each outcome contains:
- A name.
- A reference to a channel. In the case of medium, this is the reference of the batch email channel that batches emails.
- Optionally, some options. For medium, the only option is a delay of 15. This is interpreted by the email batcher to delay sending an email for 15 minutes and then to batch it up with any other emails that have appeared in this time.
You can modify the delays for the medium and low priority email if you like.
The batch email channel will always send all available emails, so medium priority emails can be combined with previously unsent low-priority emails, and will be sent within the medium priority time. The times are slightly longer than the stated delays to allow for the scheduler processing.
Changing the rules - examples
The default rules apply to everyone. You can edit it to provide more detailed rules. See Notification rules for a detailed account of the rule format. This section provides some examples. Rules are processed in sequence, and you should add your rules above a catch-all rule at the bottom of the list.
The rule data field does not validate that you have entered correct JSON. Check what you have entered using https://jsonlint.com or a similar validator to ensure you have no JSON errors. (A rule maintenance front-end will be added; manual rule maintenance has not been designed for the convenience of end users.)
In the examples below, the rule objects are shown. Combine all the rules you want within a JSON array, i.e. starting with [, separated by commas, and a ] at the end.
Example 1 - see what's going on
Use the outcome of "log" to copy the messages into the notification manager log. Do not set end, or set it to false, so that processing continues after the rule. This is useful to understand what values are available for matching.
{
"match": {
"recipient": true
},
"outcome": "log"
}Look in the notification Log to see the incoming notifications. Each log entry has two structures. The first is an options structure, which is used in the matching. The second is the full notification structure.
Example 2 - make chat high priority
Chat messages have an event_type_reference of "chat", and we can use this to make them high priority. Put this above the default rule.
{
"match": {
"recipient": true,
"event_type_reference": "chat"
},
"outcome": "high",
"end": true
}Example 3 - ignore assignment acceptance
Some processes produce a notification when assignments are accepted, which is not necessarily interesting.
{
"match": {
"recipient": true,
"event_type_reference": "assignmentAccepted"
},
"outcome": false,
"end": true
}The outcome of false means "do nothing".
Example 4 - make project notifications low priority, except for the project manager
If there is a large project with a lot of people involved, most people won't want to see the notifications very often, but the project manager will.
Use the group_path property to filter the messages.
{
"match": {
"recipient": true,
"group_path": "projects/your_project",
"recipient_email_address": "project.manager@somewhere.com"
},
"outcome": "medium",
"end": true
},
{
"match": {
"recipient": true,
"group_path": "projects/your_project"
},
"outcome": "low",
"end": true
}The rules for individuals or user groups provides an alternative method for this, which is useful if there are lots of rules.
Example 5 - add a recipient
Set the recipient and recipient email address in rule options to send to another person who is not a notification recipient, or perhaps to an email group.
{
"match": {
"recipient": false,
"group_path": "projects/your_project",
},
"outcome": "low",
"options": {
"recipient": "Project Name Distribution",
"recipient_email_address": "project-distribution-list@somewhere.com"
}
}The generated email may have links to the tasks that the recipient cannot use. Consider creating something like an "infoOnly" outcome to use an alternative email template that does not generate links.
Rules for individuals or user groups
You can modify the default rule to apply to individuals by email address, as in the example above.
If you have lots of rules, a neater way to do this is to create rules for an individual user or a group of users.
To do this, create a new rule node (you can copy default to start with). You have to set the local reference of the node to match the user id of a user or the reference of a user group. There is a convention for this, which is documented in Local Reference Script. For example, to create a rule for a user with a user identifier of "user.one", you have to use a local reference of "user_2e_one" (the "." cannot be used, so we use the hexadecimal representation of its unicode value surrounded by underscores, giving "_2e_").
Rules for an individual are combined with all the individual's user group rules and default rules. Rules for an individual are applied before those for a user group, and user group rules are applied before default rules.
Changing the email templates
The email templates are held in the Templates folder. There are two templates:
- Notification email template. This is the same as the default used in the process client, and it is used for sending notifications one email at a time.
- Batch email template. This is used for sending batches of emails.
You can modify the templates as required. You can use any of the values described in Notification flattening, and can generate additional values in rule options if required. The ${system} placeholder is easier to use than attempting to concatenate the ${application} and ${main} placeholders.
For the batch email template, write the template as if it were sending a single notification, and then use HTML comments of <!--start-repeat--> and <!--end-repeat--> to indicate the part that should be repeated for each notification. You will need to look at the HTML source to check and edit these.
For example, if you were using a list to show a repeating group, you might have something like this.
<p>You have new notifications.</p>
<ul>
<!--start-repeat-->
<li>
<p><a href="${workerURL}">${worker}</a></p>
${description}
<li>
<!--end-repeat-->
</ul>
New outcomes
Notification manager comes with four outcomes. You can add more outcomes, for example with different templates, or more categories of delay, or text that is added to the emails using rule options and custom placeholders. See the other topics in the documentation for a more detailed quide.