Triggers for Editor add-ons (original) (raw)

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 an Editor add-on a trigger is used to create add-on menu items when a document is opened. In this case, you implement on onOpen(e) trigger function to create the menu items the add-on needs, possibly using the data in the event object.

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

Editor add-on trigger types

You can use most of the generic trigger types available to Apps Script projects in Editor add-ons, including simple triggersand most installable triggers. The exact set of available trigger types depends on the application being extended.

The following table shows the types of simple and installable triggers that Editor add-ons can use, and provides links to the corresponding event objects:

Event	Event object	Simple triggers	Installable triggers
OpenAn editor file is opened.	Docs onOpen event object Forms onOpen event object Sheets onOpen event object Slides onOpen event object	Docs Forms* Sheets Slidesfunction onOpen(e)	Docs Forms Sheets
InstallThe add-on is installed.	onInstall event object	Docs Forms Sheets Slidesfunction onInstall(e)
EditSpreadsheet cell content is changed.	Sheets onEdit event object	Sheetsfunction onEdit(e)	Sheets
ChangeContent in a sheet is edited or formatted.	Sheets onChange event object	Sheets
Form-submitA Google Form is submitted.	Forms form-submit event object Sheets form-submit event object	Forms Sheets
Time-driven (clock) The trigger fires at a specified time or interval.	Time-driven event object		Docs Forms Sheets Slides

* The open event for Google Forms does not occur when a user opens a form to respond, but rather when an editor opens the form to modify it.

Simple triggers in add-ons

Simple triggers use a set a reserved function names, can't use services that require authorization, and are automatically enabled for use. In some cases, a simple trigger event can be handled by an installable trigger instead.

You can add a simple trigger to an add-on by simply implementing a function with one of the following reserved names:

• onOpen(e) executes when a user opens a document, spreadsheet, or presentation. onOpen(e) also can execute when a form is opened in the editor (but not when responding to the form). It only executes if the user has permission to edit the file in question, and is most often used to createmenu items.
• onInstall(e) executes when a user installs an add-on. Usually onInstall(e)is just used to call onOpen(e); this ensures that the add-on menus appear immediately after install without requiring the user to refresh the page.
• onEdit(e) executes when a user changes a cell value in a spreadsheet. This trigger does not fire in response to cell moves, formatting, or other changes that don't alter cell values.

Restrictions

Simple triggers in add-ons are subject to the samerestrictions that govern simple triggers in other kinds of Apps Script projects. Take particular note of these restrictions when designing add-ons:

• Simple triggers do not run if a file is opened in read-only (view or comment) mode. This behavior prevents your add-on menus from being populated.
• In certain circumstances, Editor add-ons run their onOpen(e) andonEdit(e) simple triggers in a no-authorization mode. This mode presents some additional complications as outlined in theadd-on authorization model.
• Simple triggers cannot use services or take other actions that requireauthorization, except as outlined in theadd-on authorization model.
• Simple triggers cannot run for longer than 30 seconds. Take care to minimize the amount of processing done in a simple trigger function.
• Simple triggers are subject to Apps Script triggerquota limits.

Installable triggers in add-ons

Add-ons canprogrammatically create and modify installable triggerswith the Apps Script Script service. add-on installable triggers can't be created manually. Unlike simple triggers, installable triggers can use services that require authorization.

Installable triggers in add-ons don't send error emailsto the user when they encounter errors, since in most cases a user is unable to address the problem. Because of this, you should design your add-on to gracefully handle errors on behalf of user whenever possible.

Add-ons can use the following installable triggers:

• Open installable triggers execute when a user opens a document, spreadsheet, or when a form is opened in the editor (but not when responding to the form).
• Edit installable triggers execute when a user changes a cell value in a spreadsheet. This trigger does not fire in response to formatting or other changes that don't alter cell values.
• Change installable triggers execute when a user makes any change in a spreadsheet, including formatting edits and modifications to the spreadsheet itself (such as adding a row).
• Form-submit installable triggers execute when a Google Form response is submitted.
• Time-driven triggers(also called clock triggers) fire at a specific time or repeatedly on a regular time interval.

Normally, if a developer updates an add-on to use new services that require additional authorization, users are prompted to re-authorize the add-on the next time they use it.

However, add-ons that use triggers encounter special authorization challenges. Imagine an add-on that uses a trigger to monitor form submissions: a form creator might authorize the add-on the first time they use it, then leave it to run for months or years without ever reopening the form. If the add-on developer were to update the add-on to use new services that require additional authorization, the form creator would never see the re-authorization dialog because they never reopened the form, and the add-on would stop working.

Unlike triggers in regular Apps Script projects, triggers in add-ons continue to fire even if they need re-authorization. However, the script still fails if it hits a line of code that requires authorization the script does not have. To avoid this situation, developers can use the methodScriptApp.getAuthorizationInfo()to gate access to parts of code that have changed between published versions of the add-on.

Below is an example of the recommended structure to use in trigger functions to avoid authorization pitfalls. The example trigger function responds to a form-submit event within a Google Sheets add-on and, if re-authorization is required, sends the user of the add-on an alert email using templated HTML.

Code.gs

authorizationemail.html

Restrictions

Installable triggers in add-ons are subject to the samerestrictionsthat govern installable triggers in other kinds of Apps Script projects.

In addition to these restrictions, several restrictions apply to installable triggers in add-ons specifically:

• Each add-on can only have one trigger of each type, per user, per document. For instance, in a given spreadsheet, a given user can only have one edit trigger, although the user could also have a form-submit trigger or a time-driven trigger in the same spreadsheet. A different user with access to the same spreadsheet could have their own separate set of triggers.
• Add-ons can only create triggers for the file in which the add-on is used. That is, an add-on that is used in Google Doc A cannot create a trigger to monitor when Google Doc B is opened.
• Time-driven triggers cannot run more frequently than once per hour.
• Add-ons do not automatically send the user an email when code run by an installable trigger throws an exception. It is up to the developer to check for and handle failure cases gracefully.
• Add-on triggers stop firing in any of the following situations:
  • If the add-on is uninstalled by the user,
  • If the add-on is disabled in a document (if it is re-enabled, the trigger becomes operational again), or
  • If the developer unpublishes the add-on or submits a broken version to the add-on store.
• Add-on trigger functions execute until they reach code that uses an unauthorized service, at which point they stop. This is true only if the add-on is published; the same trigger in a regular Apps Script project or an unpublished add-on don't execute at all if any part of the script needs authorization.
• Installable triggers are subject to Apps Script triggerquota limits.