Page Summary

outlined_flag

• Simple triggers in Apps Script are reserved functions that run automatically on specific events like opening or editing a document.

• Installable triggers offer more features than simple triggers but require activation.

• Both simple and installable triggers pass an event object containing context information to the triggered function.

• Simple triggers have restrictions, including limitations on services that require authorization and a maximum execution time of 30 seconds.

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

Getting started

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

• onOpen(e) runs when a user opens a spreadsheet, document, presentation, orform that the user has permission to edit.
• onInstall(e) runs when a user installs anEditor add-on from withinGoogle 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 aweb appor a program sends an HTTPGET request to a web app.
• doPost(e) runs when a program sends an HTTPPOST request to a web app.

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

Restrictions

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

• The script must bebound to a GoogleSheets, Slides, Docs, or Forms file, or else be anadd-on that extends one ofthose 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,callingRange.setValue()to edit a cell does not cause the spreadsheet'sonEdit trigger to run.
• They cannot accessservices that requireauthorization. For example,a simple trigger cannot send an email because theGmail service requires authorization, buta 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 filesbecause 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 theironOpen(e)andonEdit(e) simple triggers in a no-authorization mode that presentssome 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 todoGet(e) ordoPost(e).

onOpen(e)

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

/** * The event handler triggered when opening the spreadsheet. * @param {Event} e The onOpen event. * @see https://developers.google.com/apps-script/guides/triggers#onopene */functiononOpen(e){// Add a custom menu to the spreadsheet.SpreadsheetApp.getUi()// Or DocumentApp, SlidesApp, or FormApp..createMenu("Custom Menu").addItem("First item","menuItem1").addToUi();}

onInstall(e)

TheonInstall(e) trigger runs automatically when a user installs anEditor add-on from withinGoogle Docs, Sheets, Slides, or Forms. The trigger won't run when a userinstalls the add-on from theGoogle Workspace Marketplacewebsite. Note thatthere are certain restrictions on whatonInstall(e) can do, learn more aboutauthorization.The most common use ofonInstall(e) is simply to callonOpen(e) to addcustom menus. After all, when an add-on is installed, the file is already open,and thusonOpen(e) doesn't run on its own unless the file is reopened.

/** * The event handler triggered when installing the add-on. * @param {Event} e The onInstall event. * @see https://developers.google.com/apps-script/guides/triggers#oninstalle */functiononInstall(e){onOpen(e);}

onEdit(e)

TheonEdit(e) trigger runs automatically when a user changes the value of anycell in a spreadsheet. MostonEdit(e) triggers use the information in theevent object to respond appropriately.For example, theonEdit(e) function below sets a comment on the cell thatrecords the last time it was edited.

/** * The event handler triggered when editing the spreadsheet. * @param {Event} e The onEdit event. * @see https://developers.google.com/apps-script/guides/triggers#onedite */functiononEdit(e){// Set a comment on the edited cell to indicate when it was changed.constrange=e.range;range.setNote(`Last modified:${newDate()}`);}

/** * The event handler triggered when the selection changes in the spreadsheet. * @param {Event} e The onSelectionChange event. * @see https://developers.google.com/apps-script/guides/triggers#onselectionchangee */functiononSelectionChange(e){// Set background to red if a single empty cell is selected.constrange=e.range;if(range.getNumRows()===1&&range.getNumColumns()===1&&range.getCell(1,1).getValue()===""){range.setBackground("red");}}

doGet(e) anddoPost(e)

ThedoGet(e) trigger runs automatically when a user visits aweb app or a program sends an HTTPGET requestto a web app.doPost(e) runs when a program sends an HTTPPOST request to aweb app. These triggers are demonstrated more in the guides toweb apps,HTML service,andContent service. Note thatdoGet(e) anddoPost(e) are not subject to the restrictions listed above.

Available types of triggers

If therestrictions on simple triggers keep them from meetingyour needs, aninstallable triggermight work instead. The table below summarizes which types of triggers areavailable for each type of event. For example, Google Sheets, Slides, Forms, andDocs all support simple open triggers, but only Sheets, Docs and Forms supportinstallable open triggers.

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

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