Simple Triggers (original) (raw)

Triggers let Apps Script run a function automatically when a certain event, like opening a document, occurs. Simple triggers are a set of reserved functions built into Apps Script, like the function onOpen(e), which executes when a user opens a Google Docs, Sheets, Slides, or Forms file.Installable triggers offer more capabilities than simple triggers but must be activated before use. For both types of triggers, Apps Script passes the triggered function anevent object that contains information about the context in which the event occurred.

Getting started

To use a simple trigger, simply create a function that uses one of these reserved function names:

onOpen(e) runs when a user opens a spreadsheet, document, presentation, or form that the user has permission to edit.
onInstall(e) runs when a user installs anEditor add-on from within Google Docs, Sheets, Slides, or Forms.
onEdit(e) runs when a user changes a value in a spreadsheet.
onSelectionChange(e) runs when a user changes the selection in a spreadsheet.
doGet(e) runs when a user visits a web appor a program sends an HTTP GET request to a web app.
doPost(e) runs when a program sends an HTTP POST request to a web app.

The e parameter in the function names above is anevent object that is passed to the function. The object contains information about the context that caused the trigger to fire, but using it is optional.

Restrictions

Because simple triggers fire automatically, without asking the user for authorization, they are subject to several restrictions:

The script must be bound to a Google Sheets, Slides, Docs, or Forms file, or else be anadd-on that extends one of those applications.
They do not run if a file is opened in read-only (view or comment) mode.
Script executions and API requests do not cause triggers to run. For example, calling Range.setValue()to edit a cell does not cause the spreadsheet's onEdit trigger to run.
They cannot access services that requireauthorization. For example, a simple trigger cannot send an email because theGmail service requires authorization, but a simple trigger can translate a phrase with theLanguage service, which is anonymous.
They can modify the file they are bound to, but cannot access other files because that would require authorization.
They may or may not be able to determine the identity of the current user, depending on acomplex set of security restrictions.
They cannot run for longer than 30 seconds.
In certain circumstances,Editor add-ons run their onOpen(e)and onEdit(e) simple triggers in a no-authorization mode that presents some additional complications. For more information, see theguide to the add-on authorization lifecycle.
Simple triggers are subject to Apps Script triggerquota limits.

These restrictions do not apply to doGet(e) or doPost(e).

`onOpen(e)`

The onOpen(e) trigger runs automatically when a user opens a spreadsheet, document, presentation, or form that they have permission to edit. (The trigger does not run when responding to a form, only when opening the form to edit it.) onOpen(e) is most commonly used to add custommenu items to Google Sheets, Slides, Docs, or Forms.

`onInstall(e)`

The onInstall(e) trigger runs automatically when a user installs anEditor add-on from within Google Docs, Sheets, Slides, or Forms. The trigger won't run when a user installs the add-on from theGoogle Workspace Marketplacewebsite. Note that there are certain restrictions on what onInstall(e) can do, learn more aboutauthorization. The most common use of onInstall(e) is simply to call onOpen(e) to add custom menus. After all, when an add-on is installed, the file is already open, and thus onOpen(e) doesn't run on its own unless the file is reopened.

`onEdit(e)`

The onEdit(e) trigger runs automatically when a user changes the value of any cell in a spreadsheet. Most onEdit(e) triggers use the information in theevent object to respond appropriately. For example, the onEdit(e) function below sets a comment on the cell that records the last time it was edited.

`onSelectionChange(e)`

The onSelectionChange(e) trigger runs automatically when a user changes the selection in a spreadsheet. To activate this trigger, you must refresh the spreadsheet once the trigger is added and every time the spreadsheet is opened.

If the selection moves between multiple cells in a short time, some selection change events might be skipped to reduce latency. For example, if many selection changes are made within two seconds of each other, only the first and last selection changes will activate the onSelectionChange(e) trigger.

In the example below, if an empty cell is selected, the onSelectionChange(e) function sets the cell’s background to red.

`doGet(e)` and `doPost(e)`

The doGet(e) trigger runs automatically when a user visits aweb app or a program sends an HTTP GET request to a web app. doPost(e) runs when a program sends an HTTP POST request to a web app. These triggers are demonstrated more in the guides toweb apps, HTML service, and Content service. Note that doGet(e) anddoPost(e) are not subject to the restrictions listed above.

Available types of triggers

If the restrictions on simple triggers keep them from meeting your needs, an installable triggermight work instead. The table below summarizes which types of triggers are available for each type of event. For example, Google Sheets, Slides, Forms, and Docs all support simple open triggers, but only Sheets, Docs and Forms support installable open triggers.

Event	Simple triggers	Installable triggers
Open	Sheets Slides Forms* Docs function onOpen(e)	Sheets Forms* Docs
Edit	Sheets function onEdit(e)	Sheets
Selection change	Sheets function onSelectionChange(e)
Install	Sheets Slides Forms Docs function onInstall(e)
Change	Sheets
Form submit	Sheets Forms
Time-driven (clock)		Sheets Slides Forms Docs Standalone
Get	Standalone function doGet(e)
Post	Standalone function doPost(e)