Advanced Trigger Reference

Last Updated: 22/3/2024     Tags: trigger, triggers, advanced, js, javascript
  • Switch Version
  • V5
  • V4

To learn more about advanced triggers, please read Introduction To Advanced Triggers

Setup

Advanced triggers are only available within V4. Head to the Triggers tab within your organization located in the top menu bar.

Triggers Tab

From here, you can add new triggers or edit existing triggers.

Besides the trigger code (written in JavaScript), triggers have four fields to set:

Field Description
Name Provides a human-readable name to display in the UI
External ID Sets a unique ID which can be used by external systems to refer to this specific trigger
Matches (optional) Allows a Target Expression to be used to limit the set of subscribers for whom the trigger will be executed (if not set, the trigger will be executed for any subscriber generating the appropriate events)
Events Lists one or more event type codes in response to which the trigger will be executed.

The trigger's JavaScript code must export a function called handler, which will be passed one variable: the event record which caused the trigger to be executed. Other functions may be used (e.g. for utility purposes), but will not be called directly by TaguchiMail. |

Reference

Event Object

Property Description
id Contains the event's unique identifier, used to link related events together
ref Contains the event's type code, and will be one of the codes listed in the Events field in the trigger settings
timestamp The date/time (in UTC) at which the event occurred
data The event's data, which varies depending on the event type
subscriber The subscriber responsible for the event
activity The activity to which the event relates, if available
object The object of the event, if available (mainly for admin-level events)
campaign The campaign to which the event relates, if available
parent The event which caused the current event (e.g. for a click event, the parent is the send event for the email in which the event occurred)

The event object also provides two methods which can be used to override Taguchi's default handling:

Method Description
stopPropagation() Prevents any other user-defined triggers from executing for this event
preventDefault() Prevents Taguchi's built-in event handlers from executing for this event (note: may cause undesired system operation)

Triggers execute in a global context which contains the require method providing access to the Taguchi APIs, and a console object which provides a browser-style logging interface.

Taguchi APIs (tm)

To use Taguchi APIs, the following code should be included in the trigger script:

var tm = require('tm');

The tm module exports the following functions:

Function / Properties Description
tm.notify(data[, destination]) Sends a notification email to the list ID passed in as destination (if present), or the admin user who last edited the trigger. The data parameter is an object with the following properties:
      tag A short indicator of the message type, displayed in square brackets at the start of the subject line
      description Appears in the subject line and notification heading
      body_text The plain text content of the email
      body_html The HTML content of the email
      status One of neutral (yellow warning), inactive (blue announcement), positive (green tick), negative (red error).
tm.send(activity_id, destination[, schedule_date[, options]]) Sends/schedules an activity to be sent to the subscriber(s) identified by destination. The destination parameter may be a subscriber ID (integer), or a target expression string (e.g. "subscribed list 123"). If present and in the future, schedule_date determines the date and time at which the activity will be sent. The options object may contain the following properties:
      test If true, a test version of the activity is sent
      parent_id The ID of the parent event to use for the saved/scheduled event
      request_content An XML document which may be used by the activity template to personalize the generated message.
      tm.escape(str) Converts reserved characters to XML entities, enabling a string to be inserted into a notification email or request content.