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 an
event 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.onEdit(e)
runs when a user changes a value in a spreadsheet.onInstall(e)
runs when a user installs an add-on.doGet(e)
runs when a user visits a web app or a program sends an HTTPGET
request to a web app.doPost(e)
runs when a program sends an HTTPPOST
request to a web app.
The e
parameter in the function names above is an
event 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 an add-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'sonEdit
trigger to run. - They cannot access services that require authorization. For example, a simple trigger cannot send an email because the Gmail service requires authorization, but a simple trigger can translate a phrase with the Language 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 a complex set of security restrictions.
- They cannot run for longer than 30 seconds.
- In certain circumstances,
editor add-ons run their
onOpen(e)
andonEdit(e)
simple triggers in a no-authorization mode that presents some additional complications. For more information, see the guide to the add-on authorization lifecycle. - Simple triggers are subject to Apps Script trigger quota 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 custom
menu items to Google Sheets, Slides, Docs, or
Forms.
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 the
event 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.
onInstall(e)
The onInstall(e)
trigger runs automatically when a user installs an
add-on. 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.
doGet(e)
and doPost(e)
The doGet(e)
trigger runs automatically when a user visits a
web 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 to
web apps, HTML service,
and Content service. Note that doGet(e)
and
doPost(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 trigger might 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 |
![]() ![]() ![]() ![]()
|
![]() ![]() ![]() |
Edit |
![]()
|
![]() |
Install |
![]() ![]() ![]() ![]()
|
|
Change |
![]() |
|
Form submit |
![]() ![]() |
|
Time-driven (clock) |
![]() ![]() ![]() ![]() ![]() ![]() |
|
Get |
![]() ![]()
|
|
Post |
![]() ![]()
|
* 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.