Page Summary

outlined_flag

• Installable triggers allow Apps Script functions to run automatically based on events, offering more flexibility and authorization capabilities than simple triggers.

• Installable triggers are subject to restrictions, including not running in read-only mode, not being triggered by script executions or API requests (with one exception), and always running under the creator's account.

• Time-driven triggers allow scripts to execute at specific times or intervals.

• Event-driven triggers respond to various events in Google Workspace applications, such as opening, editing, or submitting forms, and can call services requiring authorization.

• Installable triggers can be managed manually through the script editor or programmatically using the Script service.

Likesimple triggers, installable triggers letApps Script run a function automatically when a certain event,such as opening a document, occurs. Installable triggers, however, offer moreflexibility than simple triggers: they can callservicesthat requireauthorization,they offer several additional types of events including time-driven (clock)triggers, and they can be controlled programmatically. For both simple andinstallable triggers, Apps Script passes the triggered functionanevent object that contains informationabout the context in which the event occurred.

Restrictions

Even though installable triggers offer more flexibility than simple triggers,they are still subject to several restrictions:

• They don't run if a file is opened in read-only (view or comment) mode. Forstandalone scripts, users need at least view access to the script file inorder for triggers to run properly.

• Script executions and API requests do not cause triggers to run. For example,callingFormResponse.submit()to submit a new form response does not cause the form's submit trigger to run.

  Note: An exception to this restriction isForm.submitGrades(). If your codeuses anonFormSubmit trigger, callingForm.submitGrades() triggerstheonFormSubmit condition and causes an infinite loop. To prevent theinfinite loop, add code that checks whether grades already exist beforecallingsubmitGrades().

• Installable triggers always run under the account of the person who createdthem. For example, if you create an installable open trigger, it runswhen your colleague opens the document (if your colleague has edit access),but it runs as your account. This means that if you create a trigger tosend an email when a document is opened, the email is always sent fromyour account, not necessarily the account that opened the document. However,you could create an installable trigger for each account, which would resultin one email sent from each account.

• A given account cannot see triggers installed from a second account, eventhough the first account can still activate those triggers.

• Installable triggers are subject to Apps Script triggerquota limits.

Time-driven triggers

A time-driven trigger (also called a clock trigger) is similar to acron job in Unix. Time-driven triggers letscripts execute at a particular time or on a recurring interval, as frequentlyas every minute or as infrequently as once per month. (Note that anadd-on can use a time-driven triggeronce per hour at most.) The time might be slightlyrandomized—for example, if you create a recurring 9 AM trigger,Apps Script chooses a time between 9 AM and 10 AM, then keepsthat timing consistent from day to day so that 24 hours elapse before thetrigger fires again.

Event-driven triggers

Installable event-driven triggers are conceptually similar tosimple triggerslikeonOpen(), but they can respond to additional events, and they behavedifferently.

For example, the installable open trigger for Google Sheetsactivates whenever the spreadsheet is opened by any user who has edit access,just like the simpleonOpen() trigger. However, the installable version cancallservices that requireauthorization. The installableversion runs with the authorization of the user who created the trigger, evenif another user with edit access opens the spreadsheet.

There are several installable triggers forGoogle Workspace applications:

• An installableopen trigger runs when a user opens a spreadsheet,document, or form that they have permission to edit.
• An installableedit trigger runs when a user modifies a value in aspreadsheet.
• An installablechange trigger runs when a user modifies the structure of aspreadsheet itself—for example, by adding a new sheet or removing acolumn.
• An installableform submit trigger runs when a user responds to a form.There are two versions of the form-submit trigger,one for Google Forms itselfandone for Sheets if the form submits to a spreadsheet.
• An installablecalendar event trigger runs when a user's calendar eventsare updated—created, edited, or deleted.

You can use installable triggers in standalone and bound scripts. For example,a standalone script can programmatically create an installable trigger for anarbitrary Google Sheets file by callingTriggerBuilder.forSpreadsheet(key)and passing in the spreadsheet's ID.

Manage triggers manually

To manually create an installable trigger in the script editor,follow these steps:

1. Open your Apps Script project.
2. At the left, clickTriggersalarm.
3. At the bottom right, clickAdd Trigger.
4. Select and configure the type of trigger you want to create.
5. ClickSave.

Manage triggers programmatically

You can also create and delete triggers programmatically with theScript service. Start by callingScriptApp.newTrigger(functionName),which returns aTriggerBuilder.

The following example shows how to create two time-driven triggers—one thatfires every 6 hours, and one that fires every Monday at 9 a.m. (in the time zonethat your script is set to).

/** * Creates two time-driven triggers. * @see https://developers.google.com/apps-script/guides/triggers/installable#time-driven_triggers */functioncreateTimeDrivenTriggers(){// Trigger every 6 hours.ScriptApp.newTrigger("myFunction").timeBased().everyHours(6).create();// Trigger every Monday at 09:00.ScriptApp.newTrigger("myFunction").timeBased().onWeekDay(ScriptApp.WeekDay.MONDAY).atHour(9).create();}

This next example shows how to create an installable open trigger for aspreadsheet. Note that, unlike for a simpleonOpen() trigger, the script forthe installable trigger does not need to be bound to the spreadsheet. To createthis trigger from a standalone script, simply replaceSpreadsheetApp.getActive() with a call toSpreadsheetApp.openById(id).

/** * Creates a trigger for when a spreadsheet opens. * @see https://developers.google.com/apps-script/guides/triggers/installable */functioncreateSpreadsheetOpenTrigger(){constss=SpreadsheetApp.getActive();ScriptApp.newTrigger("myFunction").forSpreadsheet(ss).onOpen().create();}

To programmatically modify an existing installable trigger, you must delete itand create a new one. If you have previously stored the ID of a trigger, you candelete it by passing the ID as an argument to the function below.

/** * Deletes a trigger. * @param {string} triggerId The Trigger ID. * @see https://developers.google.com/apps-script/guides/triggers/installable */functiondeleteTrigger(triggerId){// Loop over all triggers.constallTriggers=ScriptApp.getProjectTriggers();for(letindex=0;index <allTriggers.length;index++){// If the current trigger is the correct one, delete it.if(allTriggers[index].getUniqueId()===triggerId){ScriptApp.deleteTrigger(allTriggers[index]);break;}}}

Before creating a trigger, we recommend that you verify thatthe associated function has all the necessaryOAuth permissions.

Errors in triggers

When an installable trigger fires but the function throws an exception orotherwise fails to run successfully, you don't see an error message on yourscreen. After all, when a time-driven trigger runs or another user activatesyour form-submit trigger, you might not even be at your computer.

Instead, Apps Script sends you an email like the following:

From: noreply-apps-scripts-notifications@google.comSubject: Summary of failures for Google Apps ScriptYour script has recently failed to finish successfully.A summary of the failure(s) is shown below.

The email includes a link to deactivate or reconfigure the trigger. If thescript isboundto a Google Sheets, Docs, or Formsfile, the email also includes a link to that file. These links let youdeactivate the trigger or edit the script to fix the bug.

1. Go toscript.google.com.
2. At the left, clickMy Triggers.
3. To delete a trigger, at the right of the trigger, click Moremore_vert >Delete trigger.

If a trigger is deactivated, its corresponding failure notifications are alsodeactivated. Failure notifications are an inherent part of an active trigger.Consequently, to stop receiving all failure notifications for a specifictrigger, you need to deactivate or delete the trigger itself. While a triggeris active, you can only adjust the frequency of these notifications.

Note:Simpletriggerslike`onOpen()`can'tbedeactivatedfromthispage;instead,youmustedittheappropriatescriptandremoveorrenamethe`onOpen()`function.

Triggers in add-ons

In addition to installable triggers, you can use manifest triggers inadd-ons. For more information,seeTriggers for Google Workspace add-ons.