Triggers for Google Workspace add-ons

Apps Script triggers cause a specified script function (the trigger function) to execute whenever a specified event occurs. Only certain events can cause triggers to fire, and each Google Workspace application supports a different set of events.

When a trigger fires, an event object is created. This JSON structure contains details about the event that occurred. The information in the event object structure is organized differently based on the trigger type.

Once the event object is created, Apps Script passes it as a parameter to the trigger function. The trigger function is a callback function that you must implement yourself, to take whatever actions are appropriate to respond to the event. For example, in a Google Workspace add-on that extends Gmail, you can define a trigger that creates a new card interface when the user opens a message thread. In this case, you implement a contextual callback function to create the cards making up the new UI using the data passed in the event object.

This page provides guidelines on using triggers in Google Workspace add-on projects.

Manifest triggers

Unlike Editor add-ons, Google Workspace add-ons currently can't use Apps Script simple triggers Instead, they use triggers designed specifically for Google Workspace add-ons: manifest triggers.

Manifest triggers are defined completely in the Google Workspace add-on's manifest. Examples of manifest triggers include the following:

  • Homepage triggers that build and display the add-on homepage.
  • Calendar eventOpen triggers that display a new card or take other actions when a Calendar event is opened.
  • Calendar eventUpdate triggers that display a new card or take other actions when a user edits and saves a Calendar event.
  • Drive onItemsSelected triggers that display a new card or take other actions when a user selects one or more files or folders in Drive.
  • Gmail compose triggers that display an add-on card when the user opens the add-on in the Gmail compose window.
  • Gmail contextual triggers that display a new card or take other actions when the user opens a Gmail message.
  • Editor onFileScopeGranted triggers that display a new card when users grant authorization for the drive.file OAuth scope in the current Editor document.

In the above list, only homepage triggers are non-contextual; the rest are contextual triggers. See Manifest for more information about manifest trigger definitions.

In addition to manifest triggers, Google Workspace add-ons can also use Apps Script installable triggers.

Restrictions

Manifest triggers have certain restrictions to their use.

  • These triggers are only used in Google Workspace add-on projects; they have no purpose in any other application.
  • Since they are defined in the add-on manifest and not in its code, you can't use the Apps Script Script service to create or modify these triggers.
  • Gmail contextual triggers currently can only have an unconditional criteria. This means contextual triggers fire for every email message, regardless of content.
  • Each add-on can only have one trigger of each type, per user, per document.