Notify

Create a notification, which is typically used to send an email.

This provides a simplification of the full notification functionality, suitable for use with workers. The main restrictions are:

• If there is no description, no notification is produced.
• The recipients are always all the users associated with the worker.
• Attachments are not supported.
• Notification package cannot be set (it uses the default 'notificationPackage').
• Script and communication class are always set to scriptWorkerNotification and communicationClassWorkerNotification.
• The originating user can be suppressed from the list of recipients, but other users cannot.
• Items is always set to the worker.
• Action and action URL are not supported. This is because the notifications are not shown to the user as notifications and are not dismissable - if actions are required they can be embededded in the description.
• Duplicate notification suppression is supported, but there's no support to suppress notifications by recipient (this option is only required when the lists of users change frequently).

It sends the notification to all the users associated with the worker.

It supports the following options, which can be set in config or in passed in data.

Runtime placeholders are supported. Remember to use XML escaping within the description (e.g. using %{name/xml}).

Consume events mode

In consume events mode, notify sends notification in response to published message. The request parameters to the notify step are assumed to be as they would be in a consume step that consumes published events. This means that JSON.parse(application.get('request').getString('data')).message will contain the published message, and the data property within this will contain details of the event. The format of the published message is documented in the process automation development guide. The format of the event details is documented within the createEvent() method of the WorkerScript.

Consume mode is switched on by specifying rules in the consumeEvents config option. There are multiple consume rules in an array; the first to match the incoming message is used. If there are no rules, no matching takes place. The empty rule {} will match all event messages.

Each consume rule is an object with two properties: match and notify. match provides a pattern against which incoming messages are tested, and notify provides a specification of the notification that should be produced. The notification defaults to those within the config option, except that the message property from the event details is used as the notification description.

For example, config could contain:

{
  "importance": "default",
  "consumeEvents": [
    {
      "match": {
        "data.event_type_reference": "chat"
      },
      "notify": {
        "suppressUser": true
      }
    },
    {
      "match": {
        "data.event_type_reference": "responseReceived"
      },
      "notify": {
        "importance": "success"
      }
    }
  ]
}

The match lists fields that should be matched against the incoming message, using the rules described in library.parts.ObjectPatternScript. These can be fields from the message itself (particularly topic, publicationMode and processType) or from the data (particularly event_type_reference).

The notify object lists properties to override the config properties. It defaults to {}, but can be set to false to switch off notification (later rules are not examined).

The example above could be read as:

• When you get a chat event, create a notification of default importance but suppress sending it to the originating user.
• When you get a responseReceived event, create a notification with importance of "success".
• Ignore any other events.

The match property can be set to a single value or an array of values, any of which can match, or the value true to match any value. A match is considered true if all the properties in the match are found in the message.

Because consume mode is intended to work primarily with events, the following matches are pre-set, and need to be reset if they are not required.

{
  "publicationMode": "self",
  "topic": "event",
  "data.message": true
}

The description for the notification is read from the event message field (not the event_description). This means that the notification will show the same message as the UI. However, the notification description can be set in the notify object and this can be used to build a different message, including a message built from the event data. In the example below, the event description is used as the notification description, with an additional heading.

"notify": {
  "description": "<p>New chat received</p>%{param:data.message.data.event_description}"
}

The event_options property, which is passed in when an event is created, can be used to pass arbitrary data that can be used for matching then be retrieved using placeholders. For example, if you used this to set highImportance to true, your match for this would be:

"match": {
  "data.event_options.highImportance": true
}