Notification library

Notification is a method for sending messages to users, to inform them of important information or to prompt them to take an action.

A notification is only intended as a simple information/reminder, not as a system of record. Once a user has dismissed a notification, it can be removed from their view and eventually deleted. No permanent record is kept of the notification.

Notifications are created using the Notification type. This provides:

  • A name for the notification. This is a general title, such as "Customer enquiry 4172", not the full description.
  • A description of the notification. This forms the text of the notification seen by the recipient. This should be short, but may contain a hyperlink to the action.
  • Recipients which links to the user nodes of one or more recipients (either system users nodes or nodes of type User). Multiple recipients means that the notification is visible to multiple people. If the notification requires an action, any of the recipients can take the action. If you want each recipient to take an action, you need multiple notifications.
  • Notification timestamp which indicates when the notification was created.
  • Importance which indicates the importance of the notification. This can be one of six options which reflect the standard bootstrap styling classes:
    • Default – default importance, use for lowest priority
    • Info – general information
    • Success – indicates success, use to confirm that something requested has now happened successfully
    • Warning – indicates a warning
    • Danger – indicates danger
    • Primary – indicates an action is required
    Primary, warning and danger are generally used with actions. Default, info, success, warning and danger are used when no action is required. Notifications are presented in danger, warning, primary, success, info, default order, and then oldest first within that.
  • Notification script reference which provides a binding reference for a script to process this notification, known as the notification script.
  • Node options which is a JSON structure which provides further information about the notification, and which may be used by the notification script.
  • Notification items is an optional link to a node (or multiple nodes) to which this notification relates.
  • Communication class which links to a node that identifies how this notification should be communicated.
  • Requires action which indicates that the user must perform an action as a result of the notification.
  • Action URL an optional URL which the recipient should follow to complete the action. If not given, then the user can simply mark the notification as complete. If the URL includes popup=true, the URL will be opened in a popup, as is the dialog to mark the notification as complete.

If a notification requires an action, then the following are set when the action is complete:

The notification also maintains a manifest to grant the recipients read and execute authority on the notification.

Action and hiding

Some notifications require that the recipient takes an action. Since there can be multiple recipients, any of whom can take the action, the notification must track whether the action has taken place. A notification can therefore be in one of three states,

  • Does not require action.
  • Action required.
  • Action complete.

In addition to these states, each recipient may choose to dismiss a notification, provided that either it does not require action or the action is complete. The notification is then hidden from view, though the user can show dismissed notifications until they are deleted.

Execute

The recipient has execute authority on the notification. This follows normal process library conventions. The following actions are supported:

  • complete – mark the notification as complete. If the parameter complete=true is passed, set it to complete straight away. If an action URL is present, redirect to that to perform the complete. If not, show a dialog to ask for confirmation.
  • dismiss – dismiss the notification for this user only. This sets the userdata dismiss=true for this user.
  • undismiss – undismiss the notification for this user only.

Triggers

Notification uses two triggers.

It uses the insert trigger to schedule the notification script and a deletion script.

For notifications requiring an action, it uses the update trigger to schedule the deletion script when the action is marked as complete.

Notification script

The notification script is run in the background when the trigger is inserted, and is passed the reference to the notification node in the notification parameter.

The notification script, which is run under the authority of the owner of the notification node, can do anything. However, for normal notifications, an additional script is scheduled to run after 15 minutes for each recipient, passing it the recipient and the notification. This script then looks for all notifications that have the same communication class and sends an email to the user indicating that the notifications are present. Using user data, it keeps track of which notifications it has sent to which user (using sent=true), so that it does not repeat the notifications. Notifications with a default importance do not generate emails.

Although notifications can be created for system user nodes, remember that notification scripts may expect recipients nodes to be of a different type.

Communication class

Communication class links to a node that describes how the notificaiton should be communicated. There is no strict convention for this, and the notification script does not have to access it. However, as a general convention, it is a node of type Node Options, the Node options field of which defines a set of options for the communication, which are extended and can be overridden by the Node options on the notification itself.

Importance

The importance nodes are of type Node Options, and the Node options on this are used to determine how notifications of that importance should be processed. The following properties are supported:

retention Number of days that the notification should be retained.
cssClass The css class that should be used to highlight notifications with this importance.
sort Sort order.
send Indicates whether this notification should be sent to the user.

The standard importances have the following properties:

  retention cssClass sort send
Default 7   6  
Info 7 bg-info 5 true
Success 7 bg-success 4 true
Warning 7 bg-warning 2 true
Danger 7 bg-danger 1 true
Primary 7 bg-primary 3 true

Retention

All notifications are retained for the retention period specified by their importance, which is 7 days in every case, but can be deleted sooner by a notification script. For notifications requiring action, the deletion is actioned 7 days after the action has been confirmed. For other notifications, the deletion is actioned 7 days after the notification is created.

Notifications that are created solely to trigger a communication (such as those to inform a new user that they have been set up) are generally deleted by the notification script that sends the communication.

Utility Scripts

Create Notification Script provides a simple way of creating a notification node.

Display Notifications Script lists all notifications for the current user, and provides methods to manage the list of notifications.

Process support

Use Create notification to create notifications from within a process, or Notify when using the worker library.