GAS: Triggers (EN)

Triggers Temporais ou Installable Triggers

Like simple triggers, installable triggers let Apps Script run a function automatically when a certain event, such as opening a document, occurs. Installable triggers, however, offer more flexibility than simple triggers: they can call services that require authorization, they offer several additional types of events including time-driven (clock) triggers, and they can be controlled programmatically. For both simple and installable triggers, Apps Script passes the triggered function an event object that contains information about the context in which the event occurred.

Time-driven triggers

A time-driven trigger (also called a clock trigger) is similar to a cron job in Unix. Time-driven triggers let scripts execute at a particular time or on a recurring interval, as frequently as every minute or as infrequently as once per month. (Note that an add-on can use a time-driven trigger once per hour at most.) The time may be slightly randomized — for example, if you create a recurring 9 a.m. trigger, Apps Script chooses a time between 9 a.m. and 10 a.m., then keeps that timing consistent from day to day so that 24 hours elapse before the trigger fires again.

Installable Triggers

Restrictions

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

- 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 FormResponse.submit() to submit a new form response does not cause the form's submit trigger to run.
- Installable triggers always run under the account of the person who created them. For example, if you create an installable open trigger, it will run when your colleague opens the document (if your colleague has edit access), but it will run as your account. This means that if you create a trigger to send an email when a document is opened, the email will always be sent from your account, not necessarily the account that opened the document. However, you could create an installable trigger for each account, which would result in one email sent from each account.
- A given account cannot see triggers installed from a second account, even though the first account can still activate those triggers.

Time-driven triggers

G Suite application triggers

Installable triggers for G Suite applications are conceptually similar to simple triggers like onOpen(), but they can respond to additional events, and they behave differently.

For example, the installable open trigger for Google Sheets activates whenever the spreadsheet is opened by any user who has edit access, just like the simple onOpen() trigger. However, the installable version can call services that requireauthorization. The installable version runs with the authorization of the user who created the trigger, even if another user with edit access opens the spreadsheet.

There are several installable triggers for G Suite applications:

- An installable open trigger runs when a user opens a spreadsheet, document, or form that he or she has permission to edit.
- An installable edit trigger runs when a user modifies a value in a spreadsheet.
- An installable change trigger runs when a user modifies the structure of a spreadsheet itself — for example, by adding a new sheet or removing a column.
- An installable form-submit trigger runs when a user responds to a form. There are two versions of the form-submit trigger, one for Google Forms itself and one for Sheets if the form submits to a spreadsheet.

Note that, unlike with simple triggers, the script for an installable trigger does not need to be bound to a Google App. For example, a standalone script can programmatically create an installable trigger for an arbitrary Google Sheets file by calling TriggerBuilder.forSpreadsheet(key) and passing in the spreadsheet's ID.

Managing triggers manually

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

1. From the script editor, choose Edit > Current project's triggers.
2. Click the link that says: No triggers set up. Click here to add one now.
3. Under Run, select the name of function you want to trigger.
4. Under Events, select either Time-driven or the Google App that the script is bound to (for example, From spreadsheet).
5. Select and configure the type of trigger you want to create (for example, an Hour timer that runs Every hour or an On open trigger).
6. Optionally, click Notifications to configure how and when you will be contacted by email if your triggered function fails.
7. Click Save.

Managing triggers programmatically

You can also create and delete triggers programmatically with the Script service. Start by callingScriptApp.newTrigger(functionName), which returns a TriggerBuilder.

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

function createTimeDrivenTriggers() { // 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(); }

Triggers de Reação ou Simple Triggers

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, 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.

function onEdit(e){ // Set a comment on the edited cell to indicate when it was changed. var range = e.range; range.setNote('Last modified: ' + new Date()); }