Automate Your Google Workspace with Apps Script Triggers

As a Developer Relations Engineer, I often see developers looking for ways to make their Google Workspace integrations more powerful and responsive. You've built a cool script, but how do you make it run automatically? The answer lies in one of Apps Script's most fundamental features: triggers.

Triggers are the secret sauce that transforms your scripts from manual, on-demand tools into powerful, event-driven automations. They listen for specific events—like opening a document, editing a spreadsheet, or submitting a form—and run a designated function in response.

In this post, we'll take a deep dive into the world of Apps Script triggers, exploring the different types, their capabilities, and how to choose the right one for your project.

The Two Flavors of Triggers: Simple and Installable

Apps Script offers two main categories of triggers: simple triggers and installable triggers.

1. Simple Triggers: Quick and Easy Automation

Simple triggers are the easiest way to get started. They use a set of reserved function names that Apps Script automatically recognizes and executes when the corresponding event occurs.

The most common simple triggers are:

• onOpen(e): Runs when a user opens a document, spreadsheet, presentation, or form they have permission to edit.
• onInstall(e): Runs when a user installs an Editor Add-on.
• onEdit(e): Runs when a user changes the value of any cell in a spreadsheet.
• onSelectionChange(e): Runs when a user changes the selection in a spreadsheet.
• doGet(e) & doPost(e): Run in the context of a web app when it receives an HTTP GET or POST request.

A classic use case for onOpen(e) is to add a custom menu to your Google Workspace application. It's a fantastic way to expose your script's functionality directly within the user interface.

/**
 * The event handler triggered when opening the spreadsheet.
 * Adds a custom menu to the UI.
 */
function onOpen(e) {
  SpreadsheetApp.getUi()
      .createMenu('My Custom Menu')
      .addItem('Run my function', 'myFunction')
      .addToUi();
}

function myFunction() {
  SpreadsheetApp.getUi().alert('You ran the function!');
}

Key Restrictions of Simple Triggers:

While easy to use, simple triggers have important limitations you must be aware of:

• Authorization: They cannot perform actions that require user authorization. This means no sending emails, creating calendar events, or accessing other private user data.
• Execution Time: They are limited to a 30-second execution time.
• Context: They run only in files where the user has edit access. They won't run in read-only mode.
• No API Calls: They are not fired by API requests. For example, using Range.setValue() will not trigger an onEdit function.

2. Installable Triggers: Power and Flexibility

When the limitations of simple triggers get in your way, it's time to level up to installable triggers. As the name suggests, you must explicitly create (or "install") them, either manually through the Apps Script editor or programmatically.

This extra step unlocks significant power:

• Authorization: They can run services that require authorization, executing under the authority of the user who created the trigger.
• More Event Types: They support a wider range of events, including onChange for spreadsheets (which captures formatting changes, not just value edits) and onFormSubmit.
• Time-Driven Triggers: This is a huge one. You can schedule scripts to run at specific times or on a recurring interval (like a cron job). For standalone and container-bound scripts, this can be as frequently as every minute or as infrequently as once per month. Note that add-ons are limited to once per hour at most.
• Programmatic Control: You can create, modify, and delete them using the Script service.

Creating a Time-Driven Trigger Programmatically

Imagine you want to run a cleanup function every Monday morning. Here's how you'd create that trigger with code:

/**
 * Creates a time-driven trigger that runs every Monday at 9 AM.
 */
function createWeeklyTrigger() {
  // Deletes any existing triggers for this function to avoid duplicates.
  const allTriggers = ScriptApp.getProjectTriggers();
  for (const trigger of allTriggers) {
    if (trigger.getHandlerFunction() === 'cleanupFunction') {
      ScriptApp.deleteTrigger(trigger);
    }
  }

  // Creates a new trigger.
  ScriptApp.newTrigger('cleanupFunction')
      .timeBased()
      .onWeekDay(ScriptApp.WeekDay.MONDAY)
      .atHour(9)
      .create();
}

function cleanupFunction() {
  // Your cleanup logic goes here...
  console.log('Running weekly cleanup!');
}

Handling Errors

What happens when an installable trigger fails? For standalone and container-bound scripts, you won't see an error message on your screen, especially if it's a time-driven trigger that runs overnight. Instead, Apps Script will send an email to the trigger's creator summarizing the failure, with a link to reconfigure or deactivate it.

Important Note: Installable triggers created by add-ons don't send users these email notices. This is because users typically cannot address the underlying issues themselves, so add-on developers need to implement their own error handling and graceful failure mechanisms.

Triggers in Google Workspace Add-ons

Triggers are also the backbone of add-ons.

• Editor Add-ons (for Docs, Sheets, etc.) use the same simple and installable triggers we've discussed. A common pattern is using onInstall(e) to call onOpen(e) so your custom menus appear right after installation. Keep in mind that time-driven triggers in Editor Add-ons cannot run more frequently than once per hour.
• Google Workspace Add-ons use a special type called manifest triggers. These are defined directly in the add-on's appsscript.json manifest file and are used to launch the add-on's UI in response to contextual events, like opening a specific Gmail message or a Calendar event.

Which Trigger Should You Use?

Here's a quick guide to help you decide:

If you need to...	Use a Simple Trigger	Use an Installable Trigger
Add a custom menu when a file is opened	✅	✅
Run a script on a schedule (e.g., every hour)	❌	✅
Send an email or create a Calendar event	❌	✅
Respond to a Google Form submission	❌	✅
Perform a quick, non-auth action when a cell is edited	✅	✅
Have fine-grained programmatic control over the trigger	❌	✅

Conclusion

Apps Script triggers are the engine of automation in Google Workspace. By understanding the difference between simple and installable triggers and their respective strengths and limitations, you can build more intelligent, responsive, and powerful applications that save time and delight your users.

Want to learn more? Check out the official Apps Script triggers documentation and explore the event objects that get passed to your trigger functions.

So go ahead, give your scripts a life of their own. Happy scripting!