Skip to main content
Version: v5.1

Triggers

Overview#

A trigger is a rule that determines when a notification is sent. A trigger 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.
    • _permissionProfile._id: Optional. Passport permission profile ID; the script runs with the permissions defined by that profile (see Authentication in trigger scripts below).
    • _accessToken: Optional. Stored authentication token that the script uses when it runs.
    • _apiKey: Optional. Stored API key that the script uses when it runs.

Note: You can set exactly one of the _permissionProfile._id, _accessToken, or _apiKey settings as they are mutually exclusive. If none of these settings are set, then the script will run with the authentication token or API key of the user currently calling the API.

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)

Authentication in trigger scripts#

When a trigger has a script, the script runs with an identity (authentication token or API key) so it can call platform APIs. You can supply that identity in three ways:

  1. Permission profile — Set _script._permissionProfile._id to a Passport permission profile ID. The script then runs with the permissions defined by that profile. No credentials are stored on the trigger. This is the recommended approach when the script should use a fixed set of permissions defined in the Passport Service.
  2. Stored access token or API key — Store an _accessToken or _apiKey on the script at create or update. The script runs with that authentication token or API key.
  3. Caller's credentials — If you omit both a permission profile and a stored authentication token or API key, then the script will run with the authentication token or API key of the user currently calling the API.

Authorization: When you set _script._permissionProfile._id, you must have ASSIGN permission on that permission profile (in the Passport Service) in the trigger's namespace. Otherwise the create or update will be rejected, resulting in an HTTP 403 Forbidden error being returned.

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);

Note: The script will run with the current user's access token or API key.

Create trigger with permission profile#

To create an event type trigger whose script runs with a Passport Service permission profile, 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",        _permissionProfile: { _id: "<passport-permission-profile-id>" }    }}, ctx);

Note: You must have ASSIGN permission on the given permission profile in the trigger's namespace.

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);