Skip to main content
Version: v5.0

Triggers

Overview#

A trigger is a rule that determines when a notification is sent. A triggers matches received events and then initiates the sending of notifications to associated notification groups.

Triggers and custom scripts#

If the response to an event, requires additional processing, then a trigger may reference an optional custom script. When a custom script is present, this script influences the processing of matched events.

For more information about custom scripts, see the Custom scripts page.

Trigger properties#

The following properties are supported when creating a trigger:

  • _namespaces: A string array, which must contain a single item. It must also be in the owning namespace for this trigger. The user must also have create permissions in this namespace for the IRN notificationsvc:trigger:*
  • _name: An immutable user-friendly name that must be unique within the namespace.
  • _description: An optional description.
  • _groups: The set of groups that will be notified if the trigger matches. Each subscription will be retrieved, and the set of devices subscribed to that group will become the candidate set of devices to receive the notification.
  • _senders: For each candidate device, the sender associated with the trigger matching the transport type of the device will be selected. If multiple senders match the same transport type, then the sender will be selected at random. Becauseo of this, it is recommended to only reference a set of senders with unique transport types. If a candidate device does not match any sender, then a notification will not be sent to that device.
  • _templates: For each candidate device, the template associated with the trigger matching the transport type of the device will be selected. If multiple templates match the same transport type, then the template will be selected at random. Because of this it is recommended to only reference a set of templates with unique transport types. If a candidate device does not match any template, then a notification will not be sent to that device.
  • _script: Reference to a script item, with nested properties as follows:
    • _userType: The script's userType.
    • _name: Name of the function to call.

The rest of the properties available for a trigger depend on the value of the _type property.

When _type is EVENT the _email._filters property is supported. This matches patterns against incoming events.

For more details of event filter matching, please see Notification Service Events

Once a trigger is created, the following properties can be edited:

  • _description
  • _templates
  • _groups
  • _senders
  • _script (and all script-specific properties)
  • _type (and all type-specific properties)

API examples#

This section lists some useful examples of using the Notification Service API to perform operations with triggers.

For a full reference to the Subscription API, refer to the Trigger Rest API page.

Create a trigger#

To create an event type trigger, refer to the sample code below. 

const trigger = await IafNotification.createTrigger({    _namespaces: project._namespaces,    _type: "EVENT",    _event: {        _filters: {            "event", "resource.ResourceCreated",          "resource.type", "notificationsvc.Group",          "resource.namespaces", project._namespaces        }    },    _senders: [        {            _id: sender.id        }       ],    _groups: [        {            _id: group.id        }       ]    _templates: [        {            _id: template.id        }    ],    _script: {        _userType: "my-script"        _name: "processNotifications"     }}, ctx);

Update trigger#

To update the event filter of a trigger, refer to the sample code below. 

const trigger = await IafNotification.updateTrigger(trigger._id, {    _event: {        _filters: {            "event", "resource.ResourceCreated",          "resource.type", "notificationsvc.Group",          "resource.namespaces", project._namespaces        }    }}, ctx);

List triggers#

To list triggers, you must provide a query. The query must include at a minimum, a set of namespaces for which the calling user has READ permission.

The following query properties are supported, which map to the same properties used when creating/updating templates:

  • namespaces
  • name
  • type

To query for triggers in your project, refer to the sample query below. 

const triggers = await IafNotification.listTriggers({    namespaces: project._namespaces}, ctx);

Delete a trigger#

To delete a trigger, refer to the sample code below.

await IafNotification.deleteTrigger(trigger._id, ctx);